Re: Docstring question

[Christian Lynbech <chl at tbit dot dk>]

>>>>> "Daschbach" == Daschbach, John L <John.Daschbach@pnl.gov> writes:

Wrt. 

Daschbach> Without a metadata system it seems inevitable that a very
Daschbach> large amount of hand work will be required to produce a
Daschbach> manual which is organized by topic.

and

Daschbach> Another issue is that of examples.

I think we should take things a step at a time. 

It is clear that docstrings cannot become the be-all-end-all approach
to documentation. There will still be a need for properly written
manuals, whether these are somehow integrated into the sourcecode or
maintained as separate entities.

To me docstrings should be considered the equivalent of UNIX commands
--help option rather than as the equivalent of man pages.

Daschbach> (documentation VALUE 'syntax)
Daschbach> (documentation VALUE 'use)
Daschbach> (documentation VALUE 'class 'primary)
Daschbach> (documentation VALUE 'class 'list)
Daschbach> (documentation VALUE 'example)

The idea is good, but I do not think we should make it
mandatory. 

Thinking along the lines of using object properties for documentation
storage, we could have something like

        (documentation OBJECT EXPLANATION [PROPERTY])

where OBJECT is what we want to document, EXPLANATION the
documentation content (typically a string, but could also be some sort
of pointer, for instance an URL object if we had something like that).

The optional argument PROPERTY would be one out of a small list of
standard documentation classes, such that having no property would
store EXPLANATION under the `documentation' property whereas using the
`syntax' would store EXPLANATION under the `documentation-syntax'
property.

Retrieving object documentation would then look up all relevant
properties and combine them in a standard fashion.

---------------------------+--------------------------------------------------
Christian Lynbech          | Ericsson Telebit A/S                       
Fax:   +45 8628 8186       | Fabrikvej 11, DK-8260 Viby J
Phone: +45 8628 8177 + 28  | email: chl@tbit.dk --- URL: http://www.tbit.dk
---------------------------+--------------------------------------------------
Hit the philistines three times over the head with the Elisp reference manual.
                                        - petonic@hal.com (Michael A. Petonic)