[BuildLibcalls, Attrs] Support more variants of C++'s new, add attributes for C+...
[lldb.git] / 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``