[edit] Revise NMLib Documentation
When we're documenting code, we generally like the documentation to live with the code itself - that way, when the code changes, we change the docs at the same time (is the idea, anyway!).
NMLib lives in src/libs/nmap, and the comments we're interested in live in the various C files. An example of one looks like this:
/** Used to write decimal properties to NMAP.
Remarks
- Sends the PROPSET command to NMAP and processes the response
- processes 6000 response lines encountered
@return
- 1000 on success
- other values between 1001 and 9999 indicate protocol error
- negative value indicates a network error
@param conn the network connection to read the line from
@param guid the object where the property will be applied
@param propertyName is the property name to be set
@param propertyValue is the property value to be set
*/
This is fine, but doxygen - our automatic document system - doesn't really understand it. It takes much more concise comments, like:
/** * Read a configuration document from the Bongo Store, and bring information * from that document into the agent * \param config BongoConfigItem array which defines configuration * \param filename Filename we wish to read from the store * \return Whether or not we were successful */ BOOL ReadBongoConfiguration(BongoConfigItem *config, char *filename)
However, if you compare the two, you can see that they're actually pretty similar - e.g., you turn @param into \param, @return into \return, etc.
A patch to turn the former into the latter would be very welcome. If you have Bongo checked out, you can install doxygen and 'make docs' to build the doxygen output.