[DOC-SIG] Doc strings debate

[Daniel Larsson]

This is a multi-part message in MIME format.

------=_NextPart_000_0014_01BCF1FF.70210D20
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit


-----Original Message-----
From: Guido van Rossum <guido@CNRI.Reston.Va.US>
To: doc-sig@python.org <doc-sig@python.org>
Date: den 15 november 1997 19:29
Subject: [DOC-SIG] Doc strings debate


>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.

There is actually one other action you might want to consider if gendoc
doesn't
fit your needs: Propose what it should do and perhaps we can evolve gendoc
towards that.

What we could do is to figure out an API for extracting information out of
docstrings
which we can use for different kind of tools, such as doc generating tools
(I don't
like writing reference manuals separately, so I want tools that generate
printed
documents), class browsers, etc.

>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
>_______________
>

------=_NextPart_000_0014_01BCF1FF.70210D20
Content-Type: text/x-vcard;
	name="Daniel Larsson.vcf"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
	filename="Daniel Larsson.vcf"

BEGIN:VCARD
N:Larsson;Daniel
FN:Daniel Larsson
ORG:ABB Industrial Systems AB;LKD
TITLE:Software Engineer
ADR;WORK:;;;V=E4ster=E5s;;;Sweden
LABEL;WORK;ENCODING=3DQUOTED-PRINTABLE:V=3DE4ster=3DE5s=3D0D=3D0ASweden
URL:http://starship.skyport.net/crew/danilo
EMAIL;PREF;INTERNET:Daniel.Larsson@vasteras.mail.telia.com
END:VCARD

------=_NextPart_000_0014_01BCF1FF.70210D20--


_______________
DOC-SIG  - SIG for the Python Documentation Project

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