Re: Emacs tool for docstrings

["Greg J. Badros" <gjb at cs dot washington dot edu>]

mstachow@alum.mit.edu writes:

> Mikael Djurfeldt wrote:
> > 
> > (I'd better repeat this in a letter with fewer lines in order to
> > increase reading probability. :)
> > 
> > I could contribute an editing tool tomorrow morning (have to go to bed
> > now).  The tool will at least be able to remove/add \n\ (or break into
> > multiple strings).
> > 
> > Tomorrow morning, I'd like to use this tool to fix the docstrings and
> > commit this so that the development sources are ANSI compliant.
> > 
> > Do I have a go signal for this change?
> > 
> > Which version would you like me to use?  \n\ or "..." "..." ?
> 
> On second thought, I like "..." "..." better, ignore my previous
> message to the contrary. Let's have the docstrings not contain newlines
> except explicit ones for paragraph breaks.

Just be careful about not forgetting the whitespace at the end of the
strings.  E.g., the below is *wrong*:

"This function does something."
"Here is what it does.  It takes this arg and"
"that arg, etc."


Instead, be sure we get:

"This function does something. "
"Here is what it does.  It takes this arg and "
"that arg, etc. "

And I think it may be better to actually have a newline at the end of
the synopsis string:

"This function does something.\n"
"Here is what it does.  It takes this arg and "
"that arg, etc. "

but I don't think the Emacs commands should do that.

Be sure to test with the docstrings in numbers.c -- there are embedded
backslashed quotes there that may bite your regular expressions.  You
may want to consider just tweaking my script to do the conversion
(although using "" has more cases to handle than \n\, so its a little
bit harder).

Greg