Doxygen and License/Copyright informations

Question

I have a simple question which I could not find digging Google.

I'm moving my project's documentation from phpDoc to Doxygen, but I don't know how to write @license and @copyright together.

In my conception, @copyright is designed for my "company" (not real yet :P) name and @license the way of what I'm developing can be used: one of many CreativeCommons combinations, GNU, MIT, BSD, "under license"...

Solution 1

Building on Chris' answer, you can use the \par command to create a block similar to the built in \copyright command. For example, an alias like:

ALIASES += "license=@par License:\n"

Will allow this comment:

/** My main function.

    \copyright Copyright 2012 Chris Enterprises. All rights reserved.
    \license This project is released under the GNU Public License.
*/
int main(void){
    return 0;
}

to produce this output:

Note that with this solution, a blank line is not required before \license, and that the {} syntax is not required. This is also less likely to cause problems if you attempt to generate documentation for formats other than HTML.

Solution 2

Whilst I agree with your distinction between copyright and license information, it seems that doxygen doesn't offer separate commands for these. In fact, from the documentation of the \author command the command \copyright is used to indicate license information.

There are (at least) two possible things you can do here:

1. Simply combine the copyright and license information into the argument of the \copyright command:

   /** My main function.
   
       \copyright Copyright 2012 Chris Enterprises. All rights reserved.
       This project is released under the GNU Public License.
   */
   int main(void){
       return 0;
   }
   

   This generates the HTML

   

   This is almost certainly the easiest thing you can do.

2. Alternatively, the HTML which is written to produce the above image is

   <dl class="section copyright"><dt>Copyright</dt><dd>Copyright 2012 Chris Enterprises. All rights reserved. This project is released under the GNU Public License. </dd></dl>
   

   We can make use of this to define a new command called, say, license, which behaves in a similar way to the copyright command. Placing the following into the ALIASES field of the doxygen configuration file

   ALIASES += license{1}="<dl class=\"section copyright\"><dt>License</dt><dd>\1 </dd></dl>"
   

   and changing the above documentation block to

   /** My main function.
   
       \copyright Copyright 2012 Chris Enterprises. All rights reserved.
   
       \license{This project is released under the GNU Public License.}
   */
   

   we get the doxygen generated output

   

   Note that there are a couple of quirks in this second solution: there must be a blank line preceding the \license{...} command and the \license command must wrap it's argument in curly braces. You can optionally do this with the \copyright command, but the commands with arguments defined via ALIASES these must have braces.

Comments

[SDC]

I'm interested to know what's motivating the move from phpDoc to Doxygen? We've recently started using phpDoc, and I'm fairly happy with it; the new version 2 seems reasonably quick and configurable (the new-look phpDoc website is shocking though!).

[Bruno Augusto]

The second solution looks better, however I could not use it. I thought it could be something with "spacement policy" in my Doc Block so I replaced it with yours and I got the same result. I'm receiving three <p> filled, respectively, with: The <dt> definition, the text inside curly braces and a single quote. Is there any additional configuration I should enable? Before run Doxygen I made a few fine-tuning and, maybe, I disabled something accidentally.

[Chris]

I'm not sure why that would be the case. Try running doxygen with the default configuration file. Also, a number of recent questions have been solved by updating doxygen to the latest versions. Perhaps you could try that.

[Bruno Augusto]

I started with Doxygen a few days ago. I have the lastest version :)

[NinthTest]

Very useful, thanks! I played around with this a bit and came up with several additional formatting options to produce license output. I threw the Doxyfile snippet and a source code file with examples into a gist here: gist.github.com/mzipay/2c16253c401f11887c560f51586e7bd6

[einpoklum]

Why do you say "copyright" twice?