[Python-Dev] Why is documentation not inline?

[Demian Brecht]

@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 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 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