[MERGE] improvements to the docstrings of bzrlib.smart and contents.
Michael Hudson
michael.hudson at canonical.com
Wed Nov 14 17:35:18 GMT 2007
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...
> 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.
> 4. It would be nice if pydoctor didn't need backticks to provide such
> links.
Hm, that's an interesting idea. Probably not easy to do with the
framework that exists now.
Cheers,
mwh
More information about the bazaar
mailing list