Hi Jay! I would suggest placing documentation for an object or function with the *definition* of the function, class, or other entity. This means that documentation for classes go with the class definition in the header file (as you suggest) and documentation for functions go with the definition of the function, which is usually in the implementation file.
This is basically what you're suggesting, but I just clarified it and extended it to cover other entities than functions and classes. The good part about placing it with the definition is that if the definition of the entity changes, it is easy to change the documentation as well and it will therefore be more natural to keep the documentation up to date. Another issue that could be good to start to consider what modules we should use and then start documenting them as Doxygen modules/groups. Just my few cents, Mats Kindahl Jay Pipes wrote: > Hi all! > > Currently, there are a number of methods of documenting the code. I > would like to standardize on JavaDoc/Doxygen style, which is common, > industry-standard, machine-readable, and easy to use. Some of the code > is already done this way. Other parts, especially the older stuff, is > done using Monty's original SYNOPSIS style (if it has any documentation > at all!) > > One final question remains in my mind, though, which I would like to get > a decision on: > > Where should the documentation for a function or class go? In the > header (declaration) or source file (implementation)? My personal > preference is to put documentation *about* the API and classes in the > declaration area, and place implementation-specific documentation > comments within the implementation itself. > > Any other opinions? > > Jay > > _______________________________________________ > Mailing list: https://launchpad.net/~drizzle-discuss > Post to : [email protected] > Unsubscribe : https://launchpad.net/~drizzle-discuss > More help : https://help.launchpad.net/ListHelp -- Mats Kindahl Lead Software Developer Replication Team MySQL AB, www.mysql.com
begin:vcard fn:Mats Kindahl n:Kindahl;Mats org:Sun Microsystems adr;quoted-printable:;;Tegv=C3=A4gen 3;Storvreta;SE;74334;Sweden email;internet:[EMAIL PROTECTED] title:Lead Replication Software Developer x-mozilla-html:FALSE version:2.1 end:vcard
_______________________________________________ Mailing list: https://launchpad.net/~drizzle-discuss Post to : [email protected] Unsubscribe : https://launchpad.net/~drizzle-discuss More help : https://help.launchpad.net/ListHelp
