[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