Idiomatic format for a doxygen file header with license, author and copyright info?

Question

Suppose I have taken a source file named foo.c, written by John Smith in 1999, with email address [email protected], which was published under the terms of, say, GPL v2. Now, I'm making some changes to foo.c, and want to publish it myself, in 2022. One of the changes I'm making is adding doxygen comments, and specifically, a file-level doxygen comment block.

How should my license block look like, in terms of doxygen commands, their repetition, and use of spacing and indentation not to incorrectly break the linkage between text and command? Naturally, it needs to be both clear to the reader and communicate all required information.

(Answer by example would be nice.)

Answer 1

I do not know if there's a standard for this, but given that (as I write this) nobody else has answered, I might as well....

What I've typically seen in source files which have documentation comments is that the license information is included in a separate, non-documentation comment block. I think this makes sense, since the generated documentation is meant to be read by programmers, and they won't care about the license information (or at least, that's not what they'll be looking for in the documentation). The file-level documentation comment should explain things like what's in the file and how it relates to other files; basically, things that will be useful to someone who wants to understand how the code is organized. That doesn't include licensing info (unless licensing is the reason for organizing code into files in a certain way).

For your example, that might look something like this:

/* foo.c
 *
 * Copyright 1999 John Smith <[email protected]>
 * Modifications copyright 2022 einpoklum <[email protected]>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */

/**
 * This file contains the Foo struct and functions that act on it.
 *
 * ...(more documentation)...
 */