[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