Is using the doxygen @file command counter-productive?

Question

I'm having a dilemma regarding whether or not to use Doxygen's \@file (a.k.a. \file) command:

/**
 * @file my_filename.c
 *
 * etc. etc.

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 @file that'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?

Answer 1

Actually, you can have "the best of both worlds":

Use the @file command without specifying the filename!

The Doxygen documentation says:

If the file name is omitted (i.e. the line after \file is left blank) then the documentation block that contains the \file command will belong to the file it is located in.

that should resolve all of your qualms about using the command.