[Python-Dev] Why is documentation not inline? (original) (raw)

Demian Brecht demianbrecht at gmail.com
Mon May 20 03:19:08 CEST 2013

@nick: Yes, I realize what docstrings are for (I should have used that term rather than "inline" docs, my bad there :)). I think the problem that I've run into is simply inconsistencies in methods of documenting code (and the few times that it would have been helpful, what I was looking at had not been authored using docstrings).

Is the usage of docstrings a requirement (or a strong suggestion) for new commits (I didn't see anything while reading the submission guidelines)? If not, would it perhaps be a worthy addition?

On Sun, May 19, 2013 at 4:51 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:

On 20 May 2013 08:51, "Demian Brecht" <demianbrecht at gmail.com> wrote:

@benjamin: Ah, i see. I wasn't around pre-Sphinx. However, unless there's some custom build steps that I'm unaware of that may prevent it, it should still be relatively easy to maintain the desired narrative structure as long as the inline API docs are kept terse. That's what docstrings are for - abbreviated docs for use when reading the code and at the interactive prompt. The prose docs are designed to be a more discursive introduction to the full details of each operation, whereas docstrings are usually written more to provide someone that already knows what the function does with a reminder of the details. Cheers, Nick.

@antoine: Sorry, I may not have been clear. I wasn't advocating the inclusion of the /entire/ doc pages inline. I'm advocating terse documentation for the stdlib APIs and parameters. Narrative documentation can (and should be) maintained externally, but could use autodoc to include the terse references when desired. This would ensure that the same docs are available (and consistent) when reading the documentation as well as when neck-deep in code. On Sun, May 19, 2013 at 3:32 PM, Antoine Pitrou <solipsis at pitrou.net> wrote: > On Sun, 19 May 2013 15:29:37 -0700 > Demian Brecht <demianbrecht at gmail.com> wrote: >> This is more out of curiosity than to spark change (although I >> wouldn't argue against it): Does anyone know why it was decided to >> document external to source files rather than inline? >> >> When rapidly digging through source, it would be much more helpful to >> see parameter docs than to either have to find source lines (that can >> easily be missed) to figure out the intention. Case in point, I've >> been digging through cookiejar.py and request.py to figure out their >> interactions. When reading through buildopener, it took me a few >> minutes to figure out that each element of *handlers can be either an >> instance /or/ a class definition (I was looking at how to define a >> custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware >> that there's some documentation at the top of request.py, but it would >> have been helpful to have it right in the definition of buildopener. >> >> It seems like external docs is standard throughout the stdlib. Is >> there an actual reason for this? > > Have you seen the length of the documentation pages? Putting them > inline in the stdlib module would make the code much harder to skim > through. > > Regards > > Antoine. > > _> ________________________ > Python-Dev mailing list > Python-Dev at python.org > http://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > http://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com

-- Demian Brecht http://demianbrecht.github.com

Python-Dev mailing list Python-Dev at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com

-- Demian Brecht http://demianbrecht.github.com

More information about the Python-Dev mailing list