[clang-tools-extra] r367743 - [clang-doc] Update documentation

[Diego Astiazaran via cfe-commits]

Author: diegoastiazaran
Date: Fri Aug  2 19:18:06 2019
New Revision: 367743

URL: http://llvm.org/viewvc/llvm-project?rev=367743&view=rev
Log:
[clang-doc] Update documentation

HTML generator has been included in clang-tools-extra release notes.
clang-doc documentation file has been updated.

Differential Revision: https://reviews.llvm.org/D65622

Modified:
    clang-tools-extra/trunk/docs/ReleaseNotes.rst
    clang-tools-extra/trunk/docs/clang-doc.rst

Modified: clang-tools-extra/trunk/docs/ReleaseNotes.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/ReleaseNotes.rst?rev=367743&r1=367742&r2=367743&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/ReleaseNotes.rst (original)
+++ clang-tools-extra/trunk/docs/ReleaseNotes.rst Fri Aug  2 19:18:06 2019
@@ -52,7 +52,7 @@ The improvements are...
 Improvements to clang-doc
 -------------------------
 
-The improvements are...
+- :doc:`clang-doc <clang-doc>` now generates documentation in HTML format.
 
 Improvements to clang-query
 ---------------------------

Modified: clang-tools-extra/trunk/docs/clang-doc.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-doc.rst?rev=367743&r1=367742&r2=367743&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/clang-doc.rst (original)
+++ clang-tools-extra/trunk/docs/clang-doc.rst Fri Aug  2 19:18:06 2019
@@ -17,7 +17,7 @@ project. If you have any ideas or sugges
 there.
 
 Use
-=====
+===
 
 :program:`clang-doc` is a `LibTooling
 <https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a
@@ -25,19 +25,42 @@ compile command database for your projec
 see `How To Setup Tooling For LLVM
 <https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_).
 
-The tool can be used on a single file or multiple files as defined in 
-the compile commands database:
+By default, the tool will run on all files listed in the given compile commands
+database:
 
 .. code-block:: console
 
-  $ clang-doc /path/to/file.cpp -p /path/to/compile/commands
+  $ clang-doc /path/to/compile_commands.json
 
-This generates an intermediate representation of the declarations and their
-associated information in the specified TUs, serialized to LLVM bitcode.
+The tool can also be used on a single file or multiple files if a build path is
+passed with the ``-p`` flag.
 
-As currently implemented, the tool is only able to parse TUs that can be 
-stored in-memory. Future additions will extend the current framework to use
-map-reduce frameworks to allow for use with large codebases.
+.. code-block:: console
+
+  $ clang-doc /path/to/file.cpp -p /path/to/build
+
+Output
+======
+
+:program:`clang-doc` produces a directory of documentation. One file is produced
+for each namespace and record in the project source code, containing all
+documentation (including contained functions, methods, and enums) for that item.
+
+The top-level directory is configurable through the ``output`` flag:
+
+.. code-block:: console
+
+  $ clang-doc -output=output/directory/ compile_commands.json
+
+Configuration
+=============
+
+Configuration for :program:`clang-doc` is currently limited to command-line options.
+In the future, it may develop the ability to use a configuration file, but no such
+efforts are currently in progress.
+
+Options
+-------
 
 :program:`clang-doc` offers the following options:
 
@@ -60,6 +83,13 @@ map-reduce frameworks to allow for use w
     -dump                      - Dump intermediate results to bitcode file.
     -extra-arg=<string>        - Additional argument to append to the compiler command line
     -extra-arg-before=<string> - Additional argument to prepend to the compiler command line
-    -omit-filenames            - Omit filenames in output.
+    --format=<value>           - Format for outputted docs.
+      =yaml                    -   Documentation in YAML format.
+      =md                      -   Documentation in MD format.
+      =html                    -   Documentation in HTML format.
     -output=<string>           - Directory for outputting generated files.
     -p=<string>                - Build path
+    --public                   - Document only public declarations.
+    --stylesheets=<string>     - CSS stylesheets to extend the default styles.
+
+``stylesheets`` should only be used if ``format`` is set to ``html``.