[Doc-SIG] Documentation tool

[Fred L. Drake]

Robin Friedrich writes:
 > I vaguely remember this discussed last year. This implies changes to the
 > language; but requiring everyone to use a newer version (~1.6) seems weak.

  So call it version 2.0.  ;-)
  Seriously, I have a couple of (contradictory) thoughts on this.

  On the one hand, a language change will be necessary to support
per-parameter docstrings, and something could probably done such that
the basic syntax can be shared with an optional type declaration
scheme.  The parameter docstrings can be made available both at
runtime using import and by parse-based methods.
  On the other hand, I'm increasingly leaning toward separate
documentation.  As tedious as it can be, I don't find documentation
sprinkled throughout my code desirable, mostly because it obfuscates
the code as well as documents it.  (This is *not* an argument to not
support "inline" documentation; clearly both approaches can be used in 
parallel.)  I like docstrings, but mostly use them as a brief
refresher on the interface to a class or module; this is only part of
what I look for in reference documentation.  Making language changes
to support elaborate forms of documention becomes less important
here.  See also below....

 > I hate to rehash this but this brings up the age old debate over parsing
 > vs. import/introspection. The intent is to support both Python source and C
 > extension code. What are the scenarios for usage guys? How much info is
 > gathered via import vs gathered via a parser?

  The other big reason I'm not of the mind to spend a lot of effort on 
docstring-based reference documentation is that Python is simply too
dynamic for *either* of these approaches to be really effective in the 
general case.  While most modules may be just fine with either
approach, there's no way to always get it "right".  Consider:

	try:
	    import Foo
	except ImportError:
	    def func():
		"""Bogus operation."""
		pass
	else:
	    def func():
		"""Do something really neat."""
		pass

  What goes in the documentation?  This really doesn't seem like an
unusual circumstance, so the import-based methods (potentially)
generate different documentation based on whether sys.path is right
(imagine the user got PYTHONPATH wrong), and the parse-based approach
has to make an arbitrary decision, still possibly based on being able
to locate Foo.py (or Foo.dll, or Foo.so, or Foomodule.so, or ...).
  Don't get me wrong:  I still think that improved conventions and
tools can help the current situation.  Allowing parameter docstrings
("parmstrings"? ;) would definately be an improvement.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191