[MERGE] improvements to the docstrings of bzrlib.smart and contents.

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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, so I
would prefer to focus on making the docstrings legible inline.  There
are a few things here:

1. I'm not motivated to work hard at making the documentation
   pydoctor-friendly.
2. I'm not skilled at making the documentation pydoctor-friendly.
3. If making the documentation pydoctor-friendly makes it significantly
   harder to read inline, I would consider that a loss.
4. It would be nice if pydoctor didn't need backticks to provide such
   links.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHOyzV0F+nu1YWqI0RAkGVAKCHFMKvZ7W9KqV0JVy38UtkBjQ7JgCdEuYv
1gFaLCc8xBzGQqA9BhKf1Bk=
=o1lR
-----END PGP SIGNATURE-----