Debian Codegraph @

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

raw
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``