2

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?

1 Answer 1

5

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.