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

Michael Hudson michael.hudson at canonical.com
Wed Nov 14 17:43:40 GMT 2007


Robert Collins wrote:
> On Wed, 2007-11-14 at 17:35 +0000, Michael Hudson wrote:
>> Aaron Bentley wrote:
[...]
>>> so I would prefer to focus on making the docstrings legible inline.
>>> There are a few things here:
[...]
>>> 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 may have been unclear here.  The judgement call I referred to is
whether backticks make the docstrings "significantly harder to read
inline", not whether making the docstrings significantly harder to
read inline is a bad thing.

> I spend 99.99% of the time working on a code base looking at the
> inline docstrings.

The value of generated API docs is probably higher to non core devs,
it is true.

Cheers,
mwh



More information about the bazaar mailing list