6 ms·

Let me try to explain why it is that way: First, it's consistent with Python functions. The docstring for functions is below the signature as well. Second, cons

by mhils 1y ago

Let me try to explain why it is that way: First, it's consistent with Python functions. The docstring for functions is below the signature as well. Second, consider a file with only a docstring and then a variable declaration. Here it would be ambiguous if that's the module or the variable docstring. Finally, this behavior is consistent with other tools (and failed standardization efforts) in the space. So yeah - I share your sentiment, but I think it's the most pragmatic approach for pdoc. :)

atoav 1y ago
Maybe it is me, but I find that idea unhinged and aesthetically/semantically offputting to a degree you would have to force me to do it. I know that isn't rational, but hey, it is my personal taste and those may differ. I much prefer the way Rust did it, so just a separate type of comment-prefix for docstrings. In Rust a regular comment may be // this is a comment foo = 1.5; while a docstring is simply /// this shows up in docs foo = 1.5; with //! for docstrings at a module level. This is elegant. This is simple. It is a pythonic solution. Treating comments below a variable declaration implicity as a docstring is not. At the beginning of class or function declarations, ok (although I also would have prefered that to be above the declaration), but this.. I need a drink.
- mhils 1y ago
  FWIW I agree that the Rust way is nicer, but I can't impose the Rust way on Python. I guess the secret hack is to use PyO3, which pdoc supports quite well. ;)
- alextremblay 11mo ago
  not sure if this is a typo or a misunderstanding, but to be clear: pdoc does not treat a comment immediately below a variable declaration as a docstring, it treats an unassigned string immediately following a variable declaration as a docstring, same as how python treats an unassigned string literal immediately following a function signature as a docstring my_var = 5 "documentation for my_var" def my_func(): "documentation for my_func" also worth noting, pdoc didn't invent this design pattern, sphinx did (or perhaps something preceding sphinx?) and since sphinx is the documentation tool of choice by the python core devs to document python itself, i have to assume they've given this design pattern at least tacit approval... :shrug:

by mhils 1y ago

atoav 1y ago

Maybe it is me, but I find that idea unhinged and aesthetically/semantically offputting to a degree you would have to force me to do it. I know that isn't rational, but hey, it is my personal taste and those may differ. I much prefer the way Rust did it, so just a separate type of comment-prefix for docstrings. In Rust a regular comment may be // this is a comment foo = 1.5; while a docstring is simply /// this shows up in docs foo = 1.5; with //! for docstrings at a module level. This is elegant. This is simple. It is a pythonic solution. Treating comments below a variable declaration implicity as a docstring is not. At the beginning of class or function declarations, ok (although I also would have prefered that to be above the declaration), but this.. I need a drink.

mhils 1y ago
FWIW I agree that the Rust way is nicer, but I can't impose the Rust way on Python. I guess the secret hack is to use PyO3, which pdoc supports quite well. ;)
alextremblay 11mo ago
not sure if this is a typo or a misunderstanding, but to be clear: pdoc does not treat a comment immediately below a variable declaration as a docstring, it treats an unassigned string immediately following a variable declaration as a docstring, same as how python treats an unassigned string literal immediately following a function signature as a docstring my_var = 5 "documentation for my_var" def my_func(): "documentation for my_func" also worth noting, pdoc didn't invent this design pattern, sphinx did (or perhaps something preceding sphinx?) and since sphinx is the documentation tool of choice by the python core devs to document python itself, i have to assume they've given this design pattern at least tacit approval... :shrug: