# Doxygen Coding Style

###### tags: `Software Management` `DUNE`

## Default doxygen configuration

* Only parse header files under `package_name/include` (public headers) and `package_name/src` (private headers).
* Only generate html output, output file will be under `package_name/doc/html`;
* [Generate man pages]
* Configuration file is `package_name/.doxyfile`;
* Version number (git commit hash or tag if available) will be added automatically;
* Class dependency graph will be generated;
* ==[Generated doxygen file should be committed.??]== [separate branch for generated docs.]

## Always document the following:

* the author of the class and the last modification date
* the purpose of your class
* how it can be used (and/or possible caveats)
* what are the methods of the class good for?
* any use of special algorithms or certain assumptions.

## Keyword usage:

* always use the `@keyword` style
* list of commonly used keywords:
* `@file`
* `@author`
* `@date`
* `@brief`
* `@param` (enforce)
* `@return` (enforce)
* `@see`
* `@ref`
* `@page`, [`@group`, `@ingroup`]

## General coding style:

* Use Javadoc style (C-style) comment blocks staring with two `*`;
* Use `//` or `/* */` comment style for comments hidden from Doxygen only.

### Brief comment before

Add an extra `/``

    /// This method does something
    void DoSomething();

### Detailed comment before

Add an extra `*`; Note the intermediate leading `*`s.

    /** This is a method that does so
     *  much that I must write an epic 
     *  novel just to describe how much
     *  it truly does. 
     */
    void DoNothing();

### Brief comment after
Add an extra `/<`

    void DoSomething(); ///< This method does something

### Detailed comment after

==Avoid putting detailed comments after as much as you can. But if you have to, use the following style.==

Add an extra `*<`

    void DoNothing(); /**< This is a method that does so
      * much that I must write an epic 
      * novel just to describe how much
      * it truly does.
      */

## Examples

View the output html for the [file](https://home.fnal.gov/~dingpf/dune-daq-template/doc/html/Bar_8hh.html); and for the [class](https://home.fnal.gov/~dingpf/dune-daq-template/doc/html/classBar.html).

#ifndef DUNE_DAQ_TEMPLATE_BAR_HPP
#define DUNE_DAQ_TEMPLATE_BAR_HPP

/** @file Bar.hh
 *  @brief This file is a simple illustration of DUNE DAQ coding style.
 *
 *  This file contains a simple class definition. Please pay attention to
 *  the following doxygen coding style:
 *   - comments for files;
 *   - comments for classes;
 *   - commnets for functions;
 *  A style guide can be found in the style guide repo under DNNE-DAQ
 *  organization at GitHub.
 *
 *  @author P.Ding
 *  @date March 2020
 *
 */

#include <string>

/** @brief Simple class definition with two member classes and one private
 *         data member.
 *
 *  Detailed description follows here.
 *  @author P.Ding (if different from the file.
 *  @date March 2020
 */
class Bar {
 public:
  /** Constructor takes a string object.
   *
   * @param s string to be stored.
   */
  Bar(std::string s);

  /// Print out the stored string.
  std::string get(); /**< Details come here. */

  /// Or use this single line style.
  void put(std::string&); ///< Details come here.

 private:
  std::string bar_; /**< a string object */
};

#endif  // DUNE_DAQ_TEMPLATE_BAR_HPP

### Output for the file

### Output for the class