[Python-checkins] CVS: python/nondist/peps pep-0216.txt,1.2,1.3
Sun, 5 Nov 2000 08:48:58 -0800
Update of /cvsroot/python/python/nondist/peps
In directory slayer.i.sourceforge.net:/tmp/cvs-serv13154
Added requirements and problems.
RCS file: /cvsroot/python/python/nondist/peps/pep-0216.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** pep-0216.txt 2000/08/23 05:49:27 1.2
--- pep-0216.txt 2000/11/05 16:48:55 1.3
*** 7,10 ****
--- 7,94 ----
+ Named Python objects, such as modules, classes and functions, have a
+ string attribute called __doc__. If the first expression inside
+ the definition is a literal string, that string is assigned
+ to the __doc__ attribute.
+ The __doc__ attribute is called a documentation string, or docstring.
+ It is often used to summarize the interface of the module, class or
+ function. However, since there is no common format for documentation
+ string, tools for extracting docstrings and transforming those into
+ documentation in a standard format (e.g., DocBook) have not sprang
+ up in abundance, and those that do exist are for the most part
+ unmaintained and unused.
+ Perl Documentation
+ In Perl, most modules are documented in a format called POD -- Plain
+ Old Documentation. This is an easy-to-type, very low level format
+ which integrates well with the Perl parser. Many tools exist to turn
+ POD documentation into other formats: info, HTML and man pages, among
+ others. However, in Perl, the information is not available at run-time.
+ Java Documentation
+ In Java, special comments before classes and functions function to
+ document the code. A program to extract these, and turn them into
+ HTML documentation is called javadoc, and is part of the standard
+ Java distribution. However, the only output format that is supported
+ is HTML, and JavaDoc has a very intimate relationship with HTML.
+ Python Docstring Goals
+ Python documentation string are easy to spot during parsing, and are
+ also available to the runtime interpreter. This double purpose is
+ a bit problematic, sometimes: for example, some are reluctant to have
+ too long docstrings, because they do not want to take much space in
+ the runtime. In addition, because of the current lack of tools, people
+ read objects' docstrings by "print"ing them, so a tendancy to make them
+ brief and free of markups has sprung up. This tendancy hinders writing
+ better documentation-extraction tools, since it causes docstrings to
+ contain little information, which is hard to parse.
+ High Level Solutions
+ To counter the objection that the strings take up place in the running
+ program, it is suggested that documentation extraction tools will
+ concatenate a maximum prefix of string literals which appear in the
+ beginning of a definition. The first of these will also be available
+ in the interactive interpreter, so it should contain a few summary
+ Docstring Format Goals
+ These are the goals for the docstring format, as discussed ad neasum
+ in the doc-sig.
+ 1. It must be easy to type with any standard text editor.
+ 2. It must be readable to the casual observer.
+ 3. It must not contain information which can be deduced from parsing
+ the module.
+ 4. It must contain sufficient information so it can be converted
+ to any reasonable markup format.
+ 5. It must be possible to write a module's entire documentation in
+ docstrings, without feeling hampered by the markup language.
+ Docstring Contents
+ For requirement 5. above, it is needed to specify what must be
+ in docstrings.
+ At least the following must be available:
+ a. A tag that means "this is a Python ``something'', guess what"
+ b. Tags that mean "this is a Python class/module/class var/instance var..."
+ c. An easy way to include Python source code/Python interactive sessions
+ d. Emphasis/bold
+ e. List/tables
+ Rejected Suggestions
+ XML -- it's very hard to type, and too cluttered to read it