[Doc-SIG] Re: docstring signatures
Mon, 26 Mar 2001 10:42:37 -0500
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 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?
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. ;-)