[editor-hints-devel] My thoughts about markup and docstrings

[David Lichteblau]

Quoting Robert Goldman (rpgoldman at sift.info):
> That said, where would such configuration options live?  Would they be
> attached to an ASDF system (hard to see off hand how this would work),
> to a package that is documented (easier to implement, but does the
> policy of the documented symbol or that of *package* dominate?) or to an
> installation of parse-docstrings (probably not a good idea, since one
> might use multiple libraries with different configuration philosophies).

It could me much easier than all that:

A macro like ANNOTATE-DOCUMENTATION would always be used, right?  Either
directly, or wrapped by some other macro.

So let's have multiple versions of that macro.

  a) the tiny copy&pastable version that avoids a dependency and only
     "stuffs away" the documentation, to be parsed later

  b) a full-blown version PARSE-DOCSTRINGS:ANNOTATE-DOCUMENTATION
     that requires a dependency, and parses the arguments right away,
     for syntax validation, ability to document non-symbols, etc.

  c) a version called RPG-DOCSTRINGS:ANNOTATE-DOCUMENTATION (or
     actually, RPG-DOCSTRINGS:FOO, the name doesn't have to be
     identical) which also uses (SETF DOCUMENTATION) to update the main
     docstring.

Whether or not feature (c) is actually hidden in an extra system
and package RPG-DOCSTRINGS or is just a keyword argument to (b) is
something I haven't decided yet -- I just wanted to point out that it
*could* be an add-on system easily, should we choose not to include that
feature directly in (b).


d.