[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