[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