[Python-checkins] CVS: python/nondist/peps pep-0216.txt,1.2,1.3

[Moshe Zadka]

Update of /cvsroot/python/python/nondist/peps
In directory slayer.i.sourceforge.net:/tmp/cvs-serv13154

Modified Files:
	pep-0216.txt 
Log Message:
Added requirements and problems.


Index: pep-0216.txt
===================================================================
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 ----
  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.
+