On 6/21/2017 5:38 PM, Nikita Popov wrote: > Can you please clarify where functions that are declared in a header and > defined in a source file should be documented? I believe the usual > recommendation is to document in the source file, because it's closer to > the implementation and thus more likely to be updated. On the other hand, > documentation in headers only is more useful if you're just browsing code > and not using generated output. > > Nikita >
The documentation should go into the header file. Source files actually must not have documentation, because everything in there is private anyways. Unless it is exported via a header file that is. Doxygen will automatically inherit the documentation (no @inheritDoc necessary), because it understands the C code in C mode. Documentation should never document what the implementation does, only how it can be used. This gets blurry if you implement a particular, standardized algorithm (like the UUIDs) where the actual implementation suddenly becomes an important part of information that should go into the documentation. In other words, refactoring and other changes in a functions body should not require changes of the documentation. A usage change usually directly translates to a breaking change. A situation in which many places require updates (e.g. CHANGELOG, NEWS, ...) and not something a dev should do without thinking about the implications of doing so. -- Richard "Fleshgrinder" Fussenegger
signature.asc
Description: OpenPGP digital signature
