clang-tools-extra/docs/clang-doc.rst

   1 ===================
   2 Clang-Doc
   3 ===================
   4
   5 .. contents::
   6
   7 .. toctree::
   8    :maxdepth: 1
   9
  10 :program:`clang-doc` is a tool for generating C and C++ documentation from
  11 source code and comments.
  12
  13 The tool is in a very early development stage, so you might encounter bugs and
  14 crashes. Submitting reports with information about how to reproduce the issue
  15 to `the LLVM bug tracker <https://github.com/llvm/llvm-project/issues/>`_ will definitely help the
  16 project. If you have any ideas or suggestions, please to put a feature request
  17 there.
  18
  19 Use
  20 ===
  21
  22 :program:`clang-doc` is a `LibTooling
  23 <https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a
  24 compile command database for your project (for an example of how to do this
  25 see `How To Setup Tooling For LLVM
  26 <https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_).
  27
  28 The tool will process a list of files by default:
  29
  30 .. code-block:: console
  31
  32   $ clang-doc File1.cpp File2.cpp ... FileN.cpp
  33
  34 The tool can be also used with a compile commands database:
  35
  36 .. code-block:: console
  37
  38   $ clang-doc --executor=all-TUs compile_commands.json
  39
  40 To select only a subset of files from the database, use the ``--filter`` flag:
  41
  42 .. code-block:: console
  43
  44   $ clang-doc --executor=all-TUs --filter=File[0-9]+.cpp compile_commands.json
  45
  46 Output
  47 ======
  48
  49 :program:`clang-doc` produces a directory of documentation. One file is produced
  50 for each namespace and record in the project source code, containing all
  51 documentation (including contained functions, methods, and enums) for that item.
  52
  53 The top-level directory is configurable through the ``output`` flag:
  54
  55 .. code-block:: console
  56
  57   $ clang-doc --output=output/directory/ compile_commands.json
  58
  59 Configuration
  60 =============
  61
  62 Configuration for :program:`clang-doc` is currently limited to command-line options.
  63 In the future, it may develop the ability to use a configuration file, but no such
  64 efforts are currently in progress.
  65
  66 Options
  67 -------
  68
  69 :program:`clang-doc` offers the following options:
  70
  71 .. code-block:: console
  72
  73   $ clang-doc --help
  74   OVERVIEW: Generates documentation from source code and comments.
  75
  76   Example usage for files without flags (default):
  77
  78     $ clang-doc File1.cpp File2.cpp ... FileN.cpp
  79
  80   Example usage for a project using a compile commands database:
  81
  82     $ clang-doc --executor=all-TUs compile_commands.json
  83
  84   USAGE: clang-doc [options] <source0> [... <sourceN>]
  85
  86   OPTIONS:
  87
  88   Generic Options:
  89
  90     -help                      - Display available options (-help-hidden for more)
  91     -help-list                 - Display list of available options (-help-list-hidden for more)
  92     -version                   - Display the version of this program
  93
  94   clang-doc options:
  95
  96     --doxygen                   - Use only doxygen-style comments to generate docs.
  97     --extra-arg=<string>        - Additional argument to append to the compiler command line
  98                                   Can be used several times.
  99     --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
 100                                   Can be used several times.
 101     --format=<value>            - Format for outputted docs.
 102       =yaml                     -   Documentation in YAML format.
 103       =md                       -   Documentation in MD format.
 104       =html                     -   Documentation in HTML format.
 105     --ignore-map-errors         - Continue if files are not mapped correctly.
 106     --output=<string>           - Directory for outputting generated files.
 107     -p <string>                 - Build path
 108     --project-name=<string>     - Name of project.
 109     --public                    - Document only public declarations.
 110     --repository=<string>       -
 111                                   URL of repository that hosts code.
 112                                   Used for links to definition locations.
 113     --source-root=<string>      -
 114                                   Directory where processed files are stored.
 115                                   Links to definition locations will only be
 116                                   generated if the file is in this dir.
 117     --stylesheets=<string>      - CSS stylesheets to extend the default styles.
 118
 119 The following flags should only be used if ``format`` is set to ``html``:
 120 - ``repository``
 121 - ``source-root``
 122 - ``stylesheets``