On Monday 01 March 2010 15:40:25 Aaron Bentley wrote: > Julian Edwards wrote: > > Precedent. Pretty much most of our model objects already have this. Our > > doc strings are mostly awful and where they are not awful they are > > mediocre. > > Our classes which implement interfaces have deliberately content-free > docstrings, and I really wish they didn't. Having the documentation of > lp.code.model.Branch just saying "See `IBranch`." over and over is not > useful. > > It is very useful to have the documentation and the implementation in > the same place, so that the documentation can serve as a guide to > understanding the implementation. It also makes it easier to spot and > fix errors in the documentation. > > Aaron >
Huge +1. I've always hated that we document the interface and not the model. Does anyone remember why we do it that way? _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
