[Doc-SIG] Re: [Tutor] Documentation concerns.

Magnus Lyckå magnus@thinkware.se
Sat May 24 17:04:01 2003


At 14:36 2003-05-24 -0500, Ian Bicking wrote:
>One issue I see with moving the documentation into the code, is that we
>don't have any system that can represent the kind of documentation from
>the standard library as docstrings.  Typically documentation created
>from docstrings is highly (overly) structured, and does not allow items
>to be introduced in an order different from the code, or presented with
>a different structure than the code, plus there is no place for
>narrative that is not connected with a function or class.

You can always put a big blurb in the beginning of the module, but I
agree, and I argued the same in python-tutor. You can't expect that
the best structure for the implementation would be the best structure
to explain how to work with the software.

On the other hand, even if it takes some restructuring of the extracted
data, it seems that the docstrings for methods and functions should
typically contain the same information as we would have in the
corresponding part of the documentation. It seems very redundant to
write that twice.

Another issue is that it's great if documention examples are written
as doctest strings and run as part of a test suite. In that way, we
can at least verify that that part of the documentation is synchronized
with the implementation.

Maybe the best solution is some kind of mix.


--
Magnus Lycka (It's really Lyckå), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program