[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

Michael Hudson mwh at python.net
Tue Jul 25 09:29:39 MDT 2006


glyph at divmod.com writes:

>  - One-line summary: not always possible.  Following another aspect
>  of our coding standard, a "line", in a method-level docstring, is
>  at most 72 characters, you've burned a minimum of 8 in indentation,
>  and that's often not enough space to summarize.  One sentence
>  summary?  Sure.

As we've just discussed on #twisted, these one line summaries are
currently used by pydoctor -- it uses the first non-blank line of the
docstring(in terms of "lines in the source file") in the "summary
table" at the top of each page.  The long term solution is probably to
fix pydoctor to have some cleverer way of finding this summary, while
still not ending up with vast reams of text in the summary table if
someone neglects to add a summary.  Patches welcome :-) -- it's a job
that can be very easily localized to a single function, so you don't
need to try to wrap your head around any crazy code I've written...

Cheers,
mwh

-- 
  python py.py ~/Source/python/dist/src/Lib/test/pystone.py
  Pystone(1.1) time for 5000 passes = 19129.1
  This machine benchmarks at 0.261381 pystones/second





More information about the Twisted-Python mailing list