123 lines · plain
1===================2Clang-Doc3===================4 5.. contents::6 7.. toctree::8 :maxdepth: 19 10:program:`clang-doc` is a tool for generating C and C++ documentation from11source code and comments.12 13The tool is in a very early development stage, so you might encounter bugs and14crashes. Submitting reports with information about how to reproduce the issue15to `the LLVM bug tracker <https://github.com/llvm/llvm-project/issues/>`_ will definitely help the16project. If you have any ideas or suggestions, please to put a feature request17there.18 19Use20===21 22:program:`clang-doc` is a `LibTooling23<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a24compile command database for your project (for an example of how to do this25see `How To Setup Tooling For LLVM26<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_).27 28The tool will process a list of files by default:29 30.. code-block:: console31 32 $ clang-doc File1.cpp File2.cpp ... FileN.cpp33 34The tool can be also used with a compile commands database:35 36.. code-block:: console37 38 $ clang-doc --executor=all-TUs compile_commands.json39 40To select only a subset of files from the database, use the ``--filter`` flag:41 42.. code-block:: console43 44 $ clang-doc --executor=all-TUs --filter=File[0-9]+.cpp compile_commands.json45 46Output47======48 49:program:`clang-doc` produces a directory of documentation. One file is produced50for each namespace and record in the project source code, containing all51documentation (including contained functions, methods, and enums) for that item.52 53The top-level directory is configurable through the ``output`` flag:54 55.. code-block:: console56 57 $ clang-doc --output=output/directory/ compile_commands.json58 59Configuration60=============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 such64efforts are currently in progress.65 66Options67-------68 69:program:`clang-doc` offers the following options:70 71.. code-block:: console72 73 $ clang-doc --help74 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.cpp79 80 Example usage for a project using a compile commands database:81 82 $ clang-doc --executor=all-TUs compile_commands.json83 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 program93 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 line98 Can be used several times.99 --extra-arg-before=<string> - Additional argument to prepend to the compiler command line100 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 path108 --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 be116 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