Hacker News Reader

Comment by atoav | Hacker News Reader

Pdoc is great. I love it.

But there is one blemish.

They write on documenting variable assignments which don't support pythons __doc__ string:

> To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code) and include all assignment statements immediately followed by a docstring

I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.

To me that particular implementation is so bad, that I would prefer pdoc without it.

View on HN

> I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.

It’s standard to write docstrings below the declaration they refer to. What you are refering to are comments, not docstrings. I’ve been programming in Python for 15 years and I learnt this quite recently. This gives you in-editor documentation for class attributes and other non-functions.

Sphinx reads comments starting with #: above class variables and uses them for documentation.

I wonder why they didn’t take the same approach here and invented a new syntax.

Sphinx is the one who invented new syntax. I just used the syntax Python already had for docstrings, but extended it to variables.

Also, when I first wrote pdoc, it was at a time of immense frustration with both Sphinx and reST.

Both sound good, it seems like # immediately above a variable should be the first fallback.

Comments are not included in the AST. Also, Sphinx does support that syntax: https://stackoverflow.com/a/31764368/735926

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. :)

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.

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. ;)

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:

Reply on news.ycombinator.com