[MERGE] improvements to the docstrings of bzrlib.smart and contents.
Robert Collins
robertc at robertcollins.net
Wed Nov 14 17:40:03 GMT 2007
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
More information about the bazaar
mailing list