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

Michael Hudson michael.hudson at canonical.com
Wed Nov 14 17:08:45 GMT 2007


John Arbash Meinel wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Michael Hudson wrote:
>> Just responding to the one point here, as it's something that needs to
>> be sorted out before I resubmit:
>>
>> Aaron Bentley wrote:
>>
>>>>  Media carry the bytes of the requests somehow (e.g. via TCP, wrapped
>> in HTTP, or
>>>>  over SSH), and pass them to and from the protocol logic.  See the
>> overview in
>>>> -bzrlib/transport/smart/__init__.py.
>>>> +`bzrlib.smart`.
>>> Single backticks are definitely wrong, unless you're trying to make it
>>> italic.
>> They turn into links in the HTML generated by epydoc/pydoctor.  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.
> 
> Does it actually link to a nice target?

Yes.

> I thought you actually needed:
> 
>  `bzrlib.smart`_
> 
> So that it would create a link, and the `foo bar` is just to turn an
> expression that is normally 2 pieces into a single piece.

Well, that's true for reST in general, it seems epydoc does something
a little unusual here (pydoctor reuses epydoc's rendering code).

> I certainly think it is worth adding reference links.

Cool :)

Cheers,
mwh



More information about the bazaar mailing list