@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 <ncogh...@gmail.com> wrote: > > On 20 May 2013 08:51, "Demian Brecht" <demianbre...@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 <solip...@pitrou.net> >> wrote: >> > On Sun, 19 May 2013 15:29:37 -0700 >> > Demian Brecht <demianbre...@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 build_opener, 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 build_opener. >> >> >> >> 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@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@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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
