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

[David Lichteblau]

Hi,

Quoting Robert Goldman (rpgoldman at sift.info):
> I am very impressed by this design.  Is there a simple version of these
> docstrings that is visible through the existing documentation interface?
>  E.g., does parse-docstrings strip markup and then (SETF DOCUMENTATION)?

good question.

So far, I'm inclined to say "no".

For one thing, some people would probably prefer to keep traditional
docstrings and this new kind of documentation entirely separate (like
Tobias, if I understand correctly).

Also, one would want DOCUMENTATION to be available right after loading a
system.  But to parse docstrings, you would first have to load the
`parse-docstrings' system and its dependencies.  Do we really want to
force every author to depend on `parse-docstrings', in the ASDF
:DEPENDS-ON meaning of dependency?


Instead, I am hoping for a Slime contrib that would make the new
documentation available easily through Emacs.  This Slime contrib would
have to use `parse-docstrings', but I'm hoping that this kind of
dependency would be easier to accept for users.

Would the SLIME contrib replace existing functionality of
`slime-describe-symbol' to show the full documentation there, or would
we offer an entirely new Emacs mode (and keybinding to get there)?  I am
not sure, but perhaps Tobias already has ideas in this direction.


Note that in Nikodemus' original work, the function was actually called
DOCUMENTATION, or more precisely: PARSE-DOCSTRINGS:DOCUMENTATION, which
SHADOWed the normal CL:DOCUMENTATION.

I already deviated from that by renaming it to DOCUMENTATION*, which
makes the analogy to DOCUMENTATION very clear, but still avoids
confusion between the two symbols, as well as issues for users wanting
to IMPORT our package.  (And now Tobias is suggesting a further rename,
away from DOCUMENTATION*.)


d.