1=================== 2Clang-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 11source code and comments. 12 13The tool is in a very early development stage, so you might encounter bugs and 14crashes. Submitting reports with information about how to reproduce the issue 15to `the LLVM bugtracker <https://bugs.llvm.org/>`_ will definitely help the 16project. If you have any ideas or suggestions, please to put a feature request 17there. 18 19Use 20=== 21 22:program:`clang-doc` is a `LibTooling 23<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a 24compile command database for your project (for an example of how to do this 25see `How To Setup Tooling For LLVM 26<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). 27 28By default, the tool will run on all files listed in the given compile commands 29database: 30 31.. code-block:: console 32 33 $ clang-doc /path/to/compile_commands.json 34 35The tool can also be used on a single file or multiple files if a build path is 36passed with the ``-p`` flag. 37 38.. code-block:: console 39 40 $ clang-doc /path/to/file.cpp -p /path/to/build 41 42Output 43====== 44 45:program:`clang-doc` produces a directory of documentation. One file is produced 46for each namespace and record in the project source code, containing all 47documentation (including contained functions, methods, and enums) for that item. 48 49The 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 55Configuration 56============= 57 58Configuration for :program:`clang-doc` is currently limited to command-line options. 59In the future, it may develop the ability to use a configuration file, but no such 60efforts are currently in progress. 61 62Options 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 105The following flags should only be used if ``format`` is set to ``html``: 106- ``repository`` 107- ``source-root`` 108- ``stylesheets`` 109