hmm... I have come to the following conclusion: there are two types of documentation, and they are completely separate beasts, and I feel that we should start recognizing this difference.
1. reference docs: its structure mirrors the structure of the code, and it is often or best automatically generated from the source code and comments in the source code. It does not matter very much if the private methods are visible in this documentation; 2. user documentation: a manual written with the specific purpose of educating a person about how to use the specific module. its structure does not mirror that of the source code at all. It does not describe all the source code, just what is needed. There are code examples. There might be different manuals for different types of users written from different angles. Most of the recent discussions I hear about documentation blur this distinction, and I believe that this is making the discussions a little bit unfocused. Fred's approach with Python was to build (2), which is why IMHO that Python docs are so great. We need to recognize that writing documentation is a task in itself, and no amount of intelligent processing over docstrings will ever produce user manuals that are fun to read. My beef with this approach is that the docstrings are not used, and the documentation of functions has to be maintained by hand, in the doc file which is completely separate and far away. I have been proposing a way to share those bits and pieces (the docstrings) so that one could write a user manual independently, but still document the low-level functions in the docstrings and have that information pulled into the manual selectively. I feel that (1) is often not very useful. My experience working on large C++ codebases where the auto-documentation tools were working well and used consistently is that most people still used the source code rather than the generated HTML pages (and certainly this is what I did too). With emacs everything is available C-s or a tag away, or a grep away (or with LXR if you have that). I'd actually prefer to read from the source because other cues gave subtle information about the intent of the programmers (or lack of intent). However, many people want to generate that kind of documentation. We just have to make sure what our intention is. Oftentimes I feel that it is our programmer's instinct that makes us believe we can automatically generate (1), while really, it's not really possible. So anyway, it would be great if we could clarify the context of our intent in the discussions about documentation, whether we want to build (1), or (2), or to state clearly if we want to generate both from a single source, or whatever. Just an idea. cheers, _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
