[Doc-SIG] Re: docstring signatures

[Greg Ward]

On 26 March 2001, Guido van Rossum said:
> > From direct personal experience (15 or so Perl modules, some on CPAN and
> > some not, comprising ~10k LoC), I *do* think that intermingling code and
> > documentation makes it easier to update them together.
> > 
> > Note that it does not make it *absolutely* easy or painless or automatic;
> > any of those are bogus arguments.  But having code and doccs in the same
> > file definitely makes life *less* painful.
> 
> What argues against this for me is the existence of highly tuned
> language-specific editing modes in Emacs and many other text editors;
> these rarely do a good job on hybrids.

Absolutely true.  But python-mode already does a poor job of handling
docstrings -- or in fact any interesting[1] triple-quoted string.  Personally,
I wouldn't mind my docstrings being entirely one colour (say, the "string"
colour) and my Python code being colourized properly -- but even without any
formal markup in docstrings, Emacs can't handle that, so how can adding a
markup syntax make things worse?

        Greg

[1]  Eg.

    def foo (bar, baz):
        """Returns 'bar' if 'baz' is "foo", or 'baz' if 'bar' is "foo"."""

This is legitimate plain-text, and probably pretty close to legit ST, but
stuff like this throws python-mode for a loop.  I do this kind of markup all
the time myself.  (Although not that kind of semantics, thankfully. ;-)