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

[Tobias C. Rittweiler]

Yesterday I talked with David Lichtblau on #lisp, and he told me he's
currently working on structured docstrings. This subject falls under
editor-hints' scope (cf. items Documentation Retrieval, and Pretty
Docstrings in the [TODO] list.)

I promised him to write up my thoughts about the topic and post it here.


My stand on docstrings is that docstrings are totally inappropriate for
documentation purposes. In my view, docstrings should be used to
summarize what a function does in one, or two sentences for the reader
of the code, not the user of the code. 

The rationale behind that thinking is that elaborate docstrings would
take up too much screen space, and would seperate a) the body of a
function from its lambda-list, and b) the function definition
from other function definitions.

What I want is a DEFINE-DOCUMENTATION macro to define elaborate
documentation for a function, macro, &c. And I want Slime to bring me to
a) the rendered documentation of a symbol-at-point, and b) the source of
that documentation. (Cf. item Source Locations in [TODO].)


I think you probably expected comments regarding the implementational
model. I don't have any actually, as long as it's powerful enough to
reflect MarkDown and Texinfo. 

There's also Rahul Jain's DefDoc which I wanted to evaluate before
working on this. 

I know that Robert Strandh thought about this more concretly than I have
done as part of his SICL project.

  -T.

[TODO] -
  http://common-lisp.net/websvn/filedetails.php?repname=editor-hints&path=%2Ftrunk%2Feditor-hints%2FTODO&rev=0&sc=0