Tidying up

[Martin Pool]

On Fri, 2005-04-15 at 09:24 +0100, Magnus Therning wrote:

> >By the way, the reason for the strange ":todo:" tags and other things
> >in the docstrings is that it's the syntax expected by the "epydoc" API
> >documentation tool.  (See the ./build-api script.)  However I'm not
> >really sure that's useful, and it's probably more important to be
> >consistent and have something that just works when people look at the
> >help.
> 
> Ah, OK. I wasn't aware of epydoc's existence. I did check with pydoc,
> but that seems to not have much of a markup language at all. Epydoc does
> seem like something that'd be useful. I'd be more than happy to go over
> the code and create a patch that marks all comments based on what epydoc
> accepts.
> 
> I also have to say that I'm a little torn over what seems to be
> multiple-purpose comments--AFAICS they are used both to document the
> behaviour of the function and to drive the test. doctest is really cool,
> I love the idea, but my preference would be to break out the testing and
> use unittest instead.

I think doctest can have a real value when you use it to make sure that
the examples given for an API do work as intended.  I hope that bzr will
have a really good API for people to write workflow or bug tracker
integration or similar things on top, and for that audience it's good to
include examples in the API.  (Particularly because Python APIs are not
statically defined to the same extent as in C.)  Beyond that I don't
think doctest is so important.

That said, one probably only wants a couple of examples at most for each
entry point, which is not enough to thoroughly exercise it.  There are
probably too many at the moment.

(I'd also like to make a clearer indication of what is supposed to be
the stable bzrlib interface and what is internal, but that can come in
time.)

The most important interface at the moment is the command line, and
test.sh is probably a pretty good way to test that.  Most of the new
tests recently have gone into there.

I think unittest is rather ugly and unpythonic, so I don't know if I'd
really switch to that, but some tests in regular Python should be added.

-- 
Martin

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20050415/c1f6025c/attachment.pgp