On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <gu...@python.org> wrote: > On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-...@masklinn.net>wrote: > > > The points here are that there's a single source of truth (so we can't > > have conflicting docstring and rst documentation), and documentation > > becoming outdated can be noticed from both docstring and published > > documentation.
Another thing that hasn't been mentioned about docstrings vs rst docs, is that even when the text is identical, it generally isn't. By that I mean the rst docs have ReST markup, but the docstrings don't. So using autodoc doesn't just mean adding autodoc to our doc building toolchain, it *also* means adding support in pydoc for turning ReST into plain text. And that still leaves the markup in the docstring, where it will be very distracting while actually reading the source code. Which, unlike other commenters, I spend more time doing that than I do using help (and that doesn't apply to just the stdlib for me). > > > Another case of DRY madness. > > It seems too many programmers see documentation as unpleasant red tape they > want to cut through as quickly as possible, instead of an opportunity to > communicate with their *users*. To the contrary: users should be the most > important people in the world if you're writing code that's worth > documenting at all. I won't pretend that I find having to edit two places when updating fundamental documentation pleasant, but... I find that as often as not I want to word things *differently* in the docstring vs the rst docs for the same function. Sometimes the difference is subtle; most often it is an omission of detail along the lines Guido suggests. But when writing the rst version, it generally isn't that I'm simply continuing on after the first paragraph; instead, the organization of even that starting text is different, because I'm aware that the reader has a different mindset (quick help vs reference documentation) when reading the two texts.[*] As with the question of NEWS items versus checkin messages, the intended audience, or in this case the mindset of the intended audience, is *different*, and so the text should very often be different as well[**]. --David [*] I posit that this is even *more* true for those who say they only use help and only fall back to the full docs when the docstrings aren't enough. [**] I also wonder if long function docstrings have a negative impact on usability in IDEs that pop up windows with docstring information in them. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
