[MERGE] improvements to the docstrings of bzrlib.smart and contents.
Aaron Bentley
aaron.bentley at utoronto.ca
Thu Nov 15 01:25:21 GMT 2007
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Michael Hudson wrote:
> Aaron Bentley wrote:
>> Michael Hudson wrote:
>>> 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.
>>
>> Speaking only for myself, I never use the generated documentation,
>
> Maybe you should try it. Before I wrote pydoctor (for the Twisted
> project) I thought generated API docs were a waste of time, but now I
> think they can be pretty useful at times...
I don't have any dislike of generated documentation-- I just find that I
don't use it. Many projects I work on have generated documentation. In
some cases, I'm the person who set it up.
When I'm already working in editors and on the commandline, I just find
it easier to find stuff in that context, rather than switching to a
browser and finding it.
> For the most part, "pydoctor-friendly" isn't the point, it's making
> the docstrings reStructuredText.
I think you'll find that all of the things I complained about were
pydoctor-specific, not general reStructuredText.
>> 3. If making the documentation pydoctor-friendly makes it significantly
>> harder to read inline, I would consider that a loss.
>
> Well, this is a judgement call.
Yes. I thought we were switching to a more general discussion of how
much support we should give to pydoctor. So I gave a more general answer.
The backticks themselves don't harm legibility much. But if they must
be used every time we name a class or module, I view that as a big
hassle. Doxygen doesn't require this, so why should pydoctor?
Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFHO6AB0F+nu1YWqI0RAgq/AJ9E0c3qRb1VzxrN41zCG/L7fmABvACfd9HX
2dFzvfcHiU/DYwuKbL+Mn9w=
=CuB9
-----END PGP SIGNATURE-----
More information about the bazaar
mailing list