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

[Robert Goldman]

Tobias C. Rittweiler wrote:
> 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. 

I think I disagree with this pretty much totally.  If the documentation
strings were only for the reader of the code, rather than its user, then
we wouldn't need documentation strings at all.  Comments would suffice.

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

I agree that the default placement of the docstrings can make them cause
the problems that you name here.  However, I don't see that that is a
sufficient argument for making the docstrings into what I see as just a
special case of a comment.

Further, your argument above about the placement of the documentation
string can be turned on its head.  It's well known in software
engineering by now that any time one moves the documentation any
appreciable distance [1] away from the code, that documentation will
inevitably stray from describing the actual state of the code, if it's
ever furnished at all.

Best,
Robert


[1] where "distance" isn't a simple metric --- there's a big distance if
the documentation lives in a texinfo file, even more if it lives in a
file that must be edited in a different tool from the programmer's editor.