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 bug tracker <https://github.com/llvm/llvm-project/issues/>`_ 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 28The 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 34The 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 40To 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 46Output 47====== 48 49:program:`clang-doc` produces a directory of documentation. One file is produced 50for each namespace and record in the project source code, containing all 51documentation (including contained functions, methods, and enums) for that item. 52 53The 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 59Configuration 60============= 61 62Configuration for :program:`clang-doc` is currently limited to command-line options. 63In the future, it may develop the ability to use a configuration file, but no such 64efforts are currently in progress. 65 66Options 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 119The following flags should only be used if ``format`` is set to ``html``: 120- ``repository`` 121- ``source-root`` 122- ``stylesheets`` 123