LUFA/Build/DMBS/DMBS/doxygen.md

   1 DMBS - Dean's Makefile Build System
   2 ===================================
   3
   4
   5 Module: DOXYGEN
   6 -----------------
   7
   8 The DOXYGEN module provides build targets to automatically generate API
   9 documentation for a project, using the open-source Doxygen tool.
  10
  11 ## Importing This Module into a Makefile:
  12
  13 To use this module in your application makefile, add the following code to your
  14 makefile:
  15
  16     include $(DMBS_PATH)/doxygen.mk
  17
  18 ## Prerequisites:
  19
  20 This module requires the `doxygen` utility to be available in your system's
  21 `PATH` variable. The `doxygen` utility is distributed on the project's
  22 [official site](http://doxygen.org/) but is also
  23 made available in many *nix operating system's package managers.
  24
  25 ## Build Targets:
  26
  27 The following targets are supported by this module:
  28
  29 <table>
  30  <tbody>
  31    <tr>
  32     <td>doxygen</td>
  33     <td>Generate project documentation, via Doxygen.</td>
  34    </tr>
  35    <tr>
  36     <td>doxygen-create</td>
  37     <td>Create a new project Doxygen template, which can then be customized.</td>
  38    </tr>
  39    <tr>
  40     <td>doxygen-upgrade</td>
  41     <td>Upgrade an existing project Doxygen template to the latest Doxygen version.</td>
  42    </tr>
  43  </tbody>
  44 </table>
  45
  46 ## Mandatory Variables:
  47
  48 The following variables must be defined (with a `NAME = VALUE` syntax, one
  49 variable per line) in the user makefile to be able to use this module:
  50
  51 <table>
  52  <tbody>
  53    <tr>
  54     <td>N/A</td>
  55     <td>This module has no mandatory variables.</td>
  56    </tr>
  57  </tbody>
  58 </table>
  59
  60 ## Optional Variables:
  61
  62 The following variables may be defined (with a `NAME = VALUE` syntax, one
  63 variable per line) in the user makefile. If not specified, a default value will
  64 be assumed.
  65
  66 <table>
  67  <tbody>
  68    <tr>
  69     <td>DOXYGEN_CONF</td>
  70     <td>Name of the Doxygen project configuration file that should be used when generating documentation, or creating/upgrading the configuration file.</td>
  71    </tr>
  72    <tr>
  73     <td>DOXYGEN_FAIL_ON_WARNING</td>
  74     <td>Boolean, if `Y` the build will fail if Doxygen encounters any errors or warnings. If `N`, fail only on errors. Default is `Y`.</td>
  75    </tr>
  76    <tr>
  77     <td>DOXYGEN_OVERRIDE_PARAMS</td>
  78     <td>List of `NAME=VALUE` parameters which should override the values specified in the project configuration file, when building documentation.</td>
  79    </tr>
  80  </tbody>
  81 </table>
  82
  83 ## Provided Variables:
  84
  85 The following variables may be referenced in a user makefile (via `$(NAME)`
  86 syntax) if desired, as they are provided by this module.
  87
  88 <table>
  89  <tbody>
  90    <tr>
  91     <td>N/A</td>
  92     <td>This module provides no variables.</td>
  93    </tr>
  94  </tbody>
  95 </table>
  96
  97 ## Provided Macros:
  98
  99 The following macros may be referenced in a user makefile (via
 100 `$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
 101 this module.
 102
 103 <table>
 104  <tbody>
 105    <tr>
 106     <td>N/A</td>
 107     <td>This module provides no macros.</td>
 108    </tr>
 109  </tbody>
 110 </table>
 111
 112 ## Module Changelog:
 113
 114 The changes to this module since its initial release are listed below, as of the
 115 DMBS version where the change was made.
 116
 117 ### 20160403
 118 Initial release.