Code review comment for lp:~fwereade/pyjuju/fix-docstrings

As mentioned on IRC:

<niemeyer> fwereade: Thanks for the docstring changes
<niemeyer> fwereade: Very nice to have it being standardized
<niemeyer> fwereade: I'm slightly concerned it might be going overboard in terms of syntax in some cases.. not sure if the benefit of the linkage is worth the reduced readability in the code itself
<niemeyer> fwereade: Simple example:
<niemeyer> - @param instance_id: instance_id of the `ProviderMachine` you want.
<niemeyer> vs.
<niemeyer> 316 + :param str instance_id: :attr:`instance_id` of the
<niemeyer> 317 + :class:`ensemble.machine.ProviderMachine` you want.

Either way, I'm happy to experiment with this. +1!