I'm having a dilemma regarding whether or not to use Doxygen's
On the one hand, it's somewhat useful for you to use
@file, and IIANM, Doxygen relies on its presence somewhat when producing documentation.
On the other hand:
- It is redundant information - Doxygen can know what the filename is
- If you use a
@filethat's not the filename - it's confusing
- If you move a file, you have to change its
@file, which you can easily forget to do and adds noise to source control.
- The tag makes it problematic to link to the same source file from more than one place (which is perhaps not very common, but can be useful sometimes), or to splice files together (e.g. as part of code generation).
So, why is it even available? Do the cons not outweigh the pro's to significantly?