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

[Robert Goldman]

Tobias C. Rittweiler wrote:
> Robert Goldman  writes:
> 
>> Tobias C. Rittweiler wrote:
>>
>>> 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.
> 
> Perhaps. In my view, docstrings describe _what_ is done, comments _how_,
> or _why_ something is done. Therefore, docstrings and comments operate
> on two different views, the former on a conceptual, the latter on an
> implementational one.
> 
> I like the fact that these two are fontified differently. And I also
> like that docstrings are available at runtime. This is still useful for
> the bulk of functions that do not need full-fledged documentation.
> 
Ah, then I think we are not in disagreement after all!  My model of
docstrings is that they should give enough information for a programmer
who wishes to call the function (reference the variable, instantiate the
class, etc.).  So they should contain information about the type
signature of the parameters and the return value(s); describe important
side-effects; and name preconditions and postconditions if there are any.
> 
>> 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.
> 
> In my ideal world, we wouldn't use raw text files as an interchange
> format for programm text anymore. We would use a format that would allow
> us to annotate, and interlink code sections (both, spatial as well as in
> terms of time.)
> 
> You could then interlink documentation paragraphs to code sections. And
> your RCS should make sure that if a changeset touches such code
> sections, that the changeset also touches the interlinked sections (or
> explicitly specifies them as still being up-to-date.)
> 
> Current programming text files represent the control flow of a
> program in kind of an adequate manner[*], but are not so good at
> representing the runtime data flow.

I sympathize, but this kind of talk scares me.  I see it leading
inevitably to the kind of Java world, where one can't do anything unless
one accepts the tyranny of an enormous IDE like eclipse.

The Java folks have already entered this brave new world wherein one
builds what seems like an endless succession of GUIs for programs that
every day become more resistant to editing as text, and one must use an
ever-growing bloat of infrastructure with un-readable XML, beans,
tomcats and goodness only knows what all else....

Best,
Robert