Added requirements and problems.

pep-0216.txt

@@ -6,6 +6,90 @@ Status: Draft
 Type: Informational
 Created: 31-Jul-2000
 
+Abstract
+
+    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
+    lines. 
+
+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 
+           comfortably.
+
 
 
 Local Variables: