pydoc bzrlib.FOO as a review step ?

Martin Pool mbp at sourcefrog.net
Thu Oct 11 07:41:10 BST 2007


On 10/11/07, Robert Collins <robertc at robertcollins.net> 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>.

Obviously it is showing the first comment if there is no module
docstring, which is reasonable enough.

I think asking for some kind of module docstring would be fair enough.
 The question is how much detail is to be required, but we can take
that step by step through reviews.  We may even have some that are
present but not working correctly because they follow an import
statement.

The other problem with docstrings is that they give no narrative or
ordering, and there has to be something that tells people what module
to look at - that could be the bzrlib.__init__ docstring, or an
external document.

I might try using pydoc more, rather than looking at the source...

-- 
Martin



More information about the bazaar mailing list