Doc-SIG

Download

doc-sig@python.org

April 1996

1 participants
1 discussions

[PYTHON DOC-SIG] Docstrings .. formatting
by richard.jones＠BoM.GOV.AU April 19, 1996

April 19, 1996

[Guido, I've cc'ed this to you because I'm not sure if you get all the SIG lists... sorry if you get a dupe...] Warning! Warning! This email rambles! Stream of consciousness! OK, I've just finished a 3-day Java course. I've gotta say that they have definitely got a Good Thing in their class browser that interprets the documentation within the class files. Now, Python has got docstrings, which are in some ways better than comments a-la Java. They're also worse in other ways. Some of the benefits: - Nice and easy and obvious to add to modules. Some of the disadvantages: - Difficult to access. - No standard format for docstrings making a class browser type application quite difficult. At the moment, Python has two documentation sources, which can be (and at the moment, are) out of sync. And it's a pain as a developer to have to create two sets of documentation. I realise that there's some pretty printers out there that will handle some docstrings, but unfortunately they required the module to either be in Python or for them to be imported. Importing often isn't enough - you actually need to instatiate an object to access some of the docstrings. This is unacceptable. The solution seems obvious: . We need to make docstrings available to the user at the instant that the module is imported. No instantiation should be required. This would probably (definitely?) require changes to the way that docstrings are stored in the interpreter. Would it perhaps be possible to store them in one container per module? . We need to standardise the format of docstrings. This should not be difficult. Really. What I propose to this end is that we supply a list of recommended fields within the docstring, which may be as simple as `Usage:', `Description:', `See Also:', `Keywords:' etc. These fields are then defined to contain such information as, in the case of the `Description:' field, a one-line description followed by a more lengthy description if required. Extracting and using information stored this way in a docstring would be made much easier. Once the above two steps are taken, it will be much easier to create and update meaningful documentation (and using the `See Also' field, cross-references) and produce consistent pretty documentation. Comments? Richard Richard Jones, Satellite Section at the Bureau of Meteorology, Australia. MIME and PGP accepted. Work phone: +61-3-9669-4539 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0