Avoid File-Level Documentation Redundant with Other Documentation Already in the File [DI4]

Tip DI4

In object-oriented contexts, a file typically contains a single class, in which case separate file documentation is usually redundant and unnecessary - class (data type) documentation is typically sufficient. Avoid duplicating such documentation since doing so creates extra maintenance burden.

If you find yourself in a case where file-level documentation is “needed” for some reason (maybe your documentation generator requires it), then seek to use techniques that let you reference or automatically copy documentation from other places, rather than literally duplicating it in the source code files.

The following example shows how the Doxygen \copydoc tag can be used to have documentation for a class copied over to some package documentation:

## \package  package.my_class
## \copydoc  MyClass

See Leverage Re-usable Documentation Techniques for High-Level Documentation [DS23] [WHERE] for more details on available techniques regardless of what kind of documentation you might be creating.