[DOC-SIG] Doc strings debate

[Guido van Rossum]

There seem to be a number of different questions here; I'll try to
discuss them separately.  This message pertains to doc strings.  A
separate message will discuss the library reference manual.

As I see it, it's up to each project to decide what to do about doc
strings.  Some choices are:

- no doc strings

- terse text only doc strings, for quick on-line reminders only

- longer text only doc strings, mostly for reference by the programmer
  who is reading the source code (i.e. doc strings are just syntactic
  sugar for comments)

- longer doc strings with some markup (e.g. stext or a very limited
  HTML subset) that could be used to generate on-line documentation and
  printed documentation

- full "literate programming" doc strings, with elaborate markup; a
  preprocessor may be needed to extract Python source with smaller doc
  strings

The choice depends on the goals of the project as well as on the
availability of tools.  There seem to be some tools but they all seem
to have some shortcomings. The debate on what the tools should do is
endless; one of the reasons is that the project goals differ.

In my own style of working, I prefer terse or longer text-only doc
strings, since I am not interested in generating printed documentation
from the doc strings.  This means I don't have much use for tools (the
only tool that makes sense would be some kind of class browser that
has good support for displaying doc strings).  I don't think that the
availability of other tools would affect my style of working much; but
I realize it's a personal choice and I don't want to impose it on the
Python community as the only way to use doc strings.  However, I will
continue to use this style for the standard Python library.  Given
that I am doing most of the work here I think I have that prerogative.

I hope tools become available that give the authors of other projects
more choice -- as it stands, if gendoc doesn't do what you want,
you're basically forced to write your own tools.  Some of the existing
"hacks" deserve to be refined into more generally useful tools.  The
doc sig can contribute here by discussing the requirements for a
number of different tools, for projects with different ambitions.

--Guido van Rossum (home page: http://www.python.org/~guido/)

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________