On Sunday 09 December 2001 12:21, Chuck Esterbrook wrote:
> On Sunday 09 December 2001 01:11 pm, Tavis Rudd wrote:
> > Chuck,
> > I'd be happy to go with 90, or even 100, as a standard maximum
> > line width for Webware so we can end this debate and get back to
> > more productive things. Either would be better than the
> > no-wrapping situation in the current codebase.
> > Tavis
>
> Well at least we kept it on -devel. In the pre-devel days we would
> have lost half our -discuss members. :-)
Very true!
> In any case, I agree, but what I had in mind as the most productive
> next step was the doc string issues.
ok.
> But this has to be discussed as well because I have some questions:
>
> Off the top of my head I remember you mentioning:
>
> def foo(self):
>
> '''Returns a bar.'''
>
> return self
Geoff's comments and Ian's made me rethink the extra lines argument
for short docstrings that aren't likely to need rewrapping:
def foo(self):
"""Returns a bar."""
return self
For longer docstrings that have a lot in them, and must be updated to
reflect code changes, I still think it's best to politely ask authors
to include the extra lines. Though, it's no big deal if they forget.
> My problem is that multi-paragraph strings look strange because the
> first is indented but the others aren't.
> def foo(self):
>
> '''Returns a bar.
>
> Override to customize the baz.'''
>
> return self
If we follow the convention of using the first line as a short
synopsis, there's no problem here. Besides the docstring tools are
smart enough to figure out the indentation. Pydoc works fine with
either style.
BTW, we should ask that people follow convention of using the first
line as synopsis, followed by a blank line if there is more to the
docstring.
> I like this because the delimiters, paragraphs and code all line up
> and look neat (as in 'clean'). Obviously, both use the same # of
> lines.
I prefer including the blank lines, but I'm fine with either so long
as we use """.
> Questions:
>
> - You mentioned it is easier to word wrap the first style. Did you
> mean for the editor or when you wrap it by hand or what? What does
> that mean? (Sorry if I missed a clarification; I'm still catching
> up on messages.)
Emacs and a few other editors have an auto-wrapping feature that will
inteligently rewrap a block of continuous text to match your
preferred line wrapping. When reformatting docstrings I edit the
docstring, make sure there are blank lines between it and surrounding
code and then hit alt-q to rewrap. It deals with indentation
gracefully. Without the blank lines it will rewrap the code as well.
> - How well does pydoc work with these styles?
> - when spewing HTML
> - when browsing via a terminal
Both styles are fine.
> - How would the emacs developers react to a request to fully
> support syntax highlight of Python strings?
> - If the reaction is negative, we'll switch to """
I'm certain this has been proposed to the appropriate people before
and the answer was that it's too much effort for something they're
not concerned about. I can't remember where I read that, but I did
some research last time we discussed this.
Cheers,
Tavis
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
