Function documentation goes inside functions in Python, explicitly making them self-documenting. That can then be automatically picked up by any other code (like tooling for automatically generating API documentation) formalized as PEP 257, https://peps.python.org/pep-0257
Python will literally assign the content of your docstring (a triple-quoted string at the start of a function) to a special double underscored ("dunder") property called `__doc__` that any code can access; not just docs generators, but your own code as well (pretty dang useful for generating on-the-fly help output!).
Which also means that if you run into weird behaviour where a function doesn't do what you think it should do, you can just fire up the REPL, import that function, type `print(function_name.__doc__)` and presto, you have the documentation right there, specifically for the exact version you're using. You don't even need to leave your IDE if it comes with an integrated terminal.
True, I forget some people think a single line is function documentation; any function that's worth documenting is worth documenting properly, and needs multiline ;)
Why would you assume it's LLM slop when Python's been around for decades? Lots of folks are enthusiastic enough about "Python magic" to have done excellent writeups of literally ever dunder function under the sun on a single page, at a level of detail and excellence that the python documentation, bless its heart, cannot ever hope to match.
- The python docs are there to give you the information you need.
- Passion pages are there to do a deep dive into all the crazy shit you can do with that information =D
Annoyingly it pushes the type definitions away from the function body when you have a particularly long doc. It’s a cute trick but docs above would have been better.
You know what's cool: IDEs. They can do block folding. The really good ones just auto-fold function docs because you don't need to see those until you do.
It's not just a good trick: it's the right way to do it, and tooling can be (trivially) made to show you only what you need to see until you need to see more.
Yeah, it's one of those "Once you're used to writing doc strings, you have no reason to ever use anything else" but if you don't use them, it can be prohibitively laborious to move whatever alternative you're using over to "PEP-compliant".
(lots of fun dunder functions in Python that make metaprogramming a lot easier, but someone needs to tell you about)
Python will literally assign the content of your docstring (a triple-quoted string at the start of a function) to a special double underscored ("dunder") property called `__doc__` that any code can access; not just docs generators, but your own code as well (pretty dang useful for generating on-the-fly help output!).
Which also means that if you run into weird behaviour where a function doesn't do what you think it should do, you can just fire up the REPL, import that function, type `print(function_name.__doc__)` and presto, you have the documentation right there, specifically for the exact version you're using. You don't even need to leave your IDE if it comes with an integrated terminal.