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

[Tobias C. Rittweiler]

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.


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

  -T.

[*] Except for CLOS. Where flow of control can be obfuscated to death.