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 bugtracker <https://bugs.llvm.org/>`_ 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 By default, the tool will run on all files listed in the given compile commands
  29 database:
  30
  31 .. code-block:: console
  32
  33   $ clang-doc /path/to/compile_commands.json
  34
  35 The tool can also be used on a single file or multiple files if a build path is
  36 passed with the ``-p`` flag.
  37
  38 .. code-block:: console
  39
  40   $ clang-doc /path/to/file.cpp -p /path/to/build
  41
  42 Output
  43 ======
  44
  45 :program:`clang-doc` produces a directory of documentation. One file is produced
  46 for each namespace and record in the project source code, containing all
  47 documentation (including contained functions, methods, and enums) for that item.
  48
  49 The top-level directory is configurable through the ``output`` flag:
  50
  51 .. code-block:: console
  52
  53   $ clang-doc -output=output/directory/ compile_commands.json
  54
  55 Configuration
  56 =============
  57
  58 Configuration for :program:`clang-doc` is currently limited to command-line options.
  59 In the future, it may develop the ability to use a configuration file, but no such
  60 efforts are currently in progress.
  61
  62 Options
  63 -------
  64
  65 :program:`clang-doc` offers the following options:
  66
  67 .. code-block:: console
  68
  69   $ clang-doc --help
  70   USAGE: clang-doc [options] <source0> [... <sourceN>]
  71
  72   OPTIONS:
  73
  74   Generic Options:
  75
  76     -help                      - Display available options (-help-hidden for more)
  77     -help-list                 - Display list of available options (-help-list-hidden for more)
  78     -version                   - Display the version of this program
  79
  80   clang-doc options:
  81
  82     --doxygen                   - Use only doxygen-style comments to generate docs.
  83     --extra-arg=<string>        - Additional argument to append to the compiler command line
  84                                   Can be used several times.
  85     --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
  86                                   Can be used several times.
  87     --format=<value>            - Format for outputted docs.
  88       =yaml                     -   Documentation in YAML format.
  89       =md                       -   Documentation in MD format.
  90       =html                     -   Documentation in HTML format.
  91     --ignore-map-errors         - Continue if files are not mapped correctly.
  92     --output=<string>           - Directory for outputting generated files.
  93     -p=<string>                 - Build path
  94     --project-name=<string>     - Name of project.
  95     --public                    - Document only public declarations.
  96     --repository=<string>       -
  97                                   URL of repository that hosts code.
  98                                   Used for links to definition locations.
  99     --source-root=<string>      -
 100                                   Directory where processed files are stored.
 101                                   Links to definition locations will only be
 102                                   generated if the file is in this dir.
 103     --stylesheets=<string>      - CSS stylesheets to extend the default styles.
 104
 105 The following flags should only be used if ``format`` is set to ``html``:
 106 - ``repository``
 107 - ``source-root``
 108 - ``stylesheets``