Page Comparison

...

• Interface documentation should be as simple and short as possible. If it becomes long and complicated, it suggests that the module may not have a clean interface, so perhaps you should consider redesigning the module. For methods, put all the interface documentation in the method header, and leave all implementation documentation out of the header: put that in the body instead.
• The purpose of interface documentation is to describe how to use a module. It should not describe the internals of the module (if knowledge of the internals is needed to use a module, it suggests that the module doesn't represent a very clean up structure).
• In writing interface documentation, think about the contract between the module and its users; anything that affects this contract should be documented. One example is ownership of memory: if methods in the module return dynamically allocated memory, who is responsible for eventually freeing the memory? Exceptions are another example.
• Interface documentation should describe not just "what" but also "why". "What" means information such as parameter descriptions, return values, and side effects. "Why" means information such as why this class is needed (what problems does it solve?), and in what situations with this class be used? For methods it's often useful to document the situations under which a particular method should/will be invoked (this is particularly useful for callback methods, which are invoked automatically in response to external events).
• For methods, be sure to document side effects: any way this method could affect the future operation of the system, other than through value(s) returned to the caller.
• In the documentation for a method, use different words from those in the method's name. For example, for a method flushBuffer don't say "Flush the buffer" in the documentation, since that provides no new information. Instead, say something different like "Make sure that Write the buffer contents of the buffer have been written to the underlying network connection". This second form also indicates when you might want to use this method.

...

• Be precise. Just a couple of extra words can often

• Be precise

• Avoid word repetitionmake things dramatically clearer. For example, "Address of the first byte to be copied" is more precise than "Source buffer".
• Give units. For example, say "Number of bytes to copy" instead of "Buffer length".