[MERGE] improvements to the docstrings of bzrlib.smart and contents.
John Arbash Meinel
john at arbash-meinel.com
Wed Nov 14 17:03:37 GMT 2007
-----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? 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.
I certainly think it is worth adding reference links.
>
> Cheers,
> mwh
>
> PS: I recently updated the pydoctor running
> http://starship.python.net/crew/mwh/bzrlibapi/, though I think the
> only difference that really affects bzr is the recording of when
> pydoctor ran.
>
>
John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFHOyppJdeBCYSNAAMRAli6AJ4rT86mE6fBAlUMZR40Yk+JUxECkwCgqgJr
NlF0guDjnWJWduu8L2eGZ6M=
=DyNi
-----END PGP SIGNATURE-----
More information about the bazaar
mailing list