docstrings discussion

[Ian Clatworthy]

Aaron Bentley wrote:

> I think this should address all your comments.  I have added scads of
> docstrings despite philosophical objections that it violates DRY, so
> that it can get merged separately from the discussion of how much
> documentation is appropriate.

Aaron,

Thanks for the additional documentation. I forgot to reply to the
concerns you raised ...

To be clear, I agree that adding docstrings for the sake of it isn't
wise. I'd go further and say that wrong docstrings can be worse than no
docstrings. I also agree that your code does a great job of being clear
and is largely self-documenting. We all ought to be aiming for that. On
all of these points, I suspect we're in agreement.

My request for docstrings had nothing to do with helping programmers who
were viewing and/or editing the bzrlib code in vim/Emacs/whatever. It
was to do with *other* mediums for browsing the API, e.g. webpages
generated by pydoctor. Increasingly as well, smart IDEs can popup the
docstrings for API calls in balloon help. It sounds corny but it's
really useful for many developers in my experience.

Of course, many of us use vim and are working on the bzrlib code itself
so docstrings can be more trouble than value. In the medium term though,
the typical bzrlib API programmer is more likely to be treating it as a
blackbox, more like how most of us treat the standard Python library.
Catering for webpage generation tools and IDEs by writing good
docstrings is therefore something I think we need to be conscious of IMO
(without going crazy about it).

My 2c,
Ian C.