pydoc bzrlib.FOO as a review step ?

John Arbash Meinel john at arbash-meinel.com
Mon Oct 15 23:16:32 BST 2007


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Robert Collins wrote:
> I was just looking at the pack format via pydoc and I realised that most
> of our source files show simply a huge copyright statement in 'pydoc
> bzrlib.THING', under the description field.
> 
> I think that is pretty pointless, and instead we should have something
> useful. E.g. for bzrlib.repoformat.pack I want a description of packs as
> repository formats, their distinct characteristics, tradeoffs etc. That
> is the specifics for <this module>.
> 
> I'm wondering if its reasonable to assess this for all new
> <not-test-script> modules?
> 
> -Rob

I know documentation review is already supposed to be part of the review
process. Whether that is documentation in bzrlib/pack.py or in doc/.../pack.txt.

I think it would be a good idea to at least think about what the module level
documentation is.

For example, bzrlib.tag.BasicTags has no documentation on the "get_tag_dict()"
function that I can find. Which makes figuring out exactly what kind of
dictionary to return a little bit tricky (you have to parse through the
different layers to figure out that it is indeed just a plain dictionary of
Unicode:revision_id).

So yeah, we probably need to pay attention to docstrings again. And if "pydoc
module" is an easy way to do that, it seems worthwhile.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHE+bAJdeBCYSNAAMRAgNrAKCr7qxA6cBH8BKoPehSek3ufNY0fQCg0YRa
umwWkJyiEcGkiD12xXRzhT4=
=JOBF
-----END PGP SIGNATURE-----



More information about the bazaar mailing list