On 11/02/2012, at 12:47 AM, André Somers wrote: My suggestion would be this: 1) If possible, documentation goes right above the relevant code (implementation or declaration) 2) Prefer the implementation over the declaration when you have to choose 3) If neither is possible, prefer the implementation file to put your artificial \fn's and the likes
+1 This is basically what we do with our code. When documentation is in the headers, developers are less likely to update them because they know that it will trigger potentially large rebuilds. If the docs are in the .cpp file, then they will update pretty much any trivial thing because it's only going to cause that one file to be rebuilt (okay, plus maybe some subsequent relinking). I'm also a big fan of the "put the documentation close to the code" philosophy. That tends to encourage keeping the documentation up to date. -- Dr Craig Scott Computational Software Engineering Team Leader, CSIRO (CMIS) Melbourne, Australia _______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
