[MERGE] improvements to the docstrings of bzrlib.smart and contents.

[Robert Collins]

On Wed, 2007-11-14 at 17:35 +0000, Michael Hudson wrote:
> Aaron Bentley wrote:
> > Michael Hudson wrote:
> >> Is the utility of being able to click on the links in the generated
> >> documentation worth some clutter in the docstrings?  I can't decide
> >> that for bzrlib.
> >
> > Speaking only for myself, I never use the generated documentation, 
> 
> Maybe you should try it.  Before I wrote pydoctor (for the Twisted
> project) I thought generated API docs were a waste of time, but now I
> think they can be pretty useful at times...

I think they are useful but ...

> > so I would prefer to focus on making the docstrings legible inline.
> > There are a few things here:
> >
> > 1. I'm not motivated to work hard at making the documentation
> >    pydoctor-friendly.
> > 2. I'm not skilled at making the documentation pydoctor-friendly.
> 
> For the most part, "pydoctor-friendly" isn't the point, it's making
> the docstrings reStructuredText.
> 
> > 3. If making the documentation pydoctor-friendly makes it significantly
> >    harder to read inline, I would consider that a loss.
> 
> Well, this is a judgement call.

I completely agree with Aaron. I spend 99.99% of the time working on a
code base looking at the inline docstrings. Context switching to a
browser or other editor to look at something is madness. Not to mention
expensive on ram.

-Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20071115/2f01dc4f/attachment.pgp