[PATCH] D65622: [clang-doc] Update documentation

2019-08-05 Thread Julie Hockett via Phabricator via cfe-commits 
juliehockett added a comment.

Sorry for the delayed review, but a few things I caught :)

Also, please make sure to update the the release notes/flag documentation for 
the patches you have in progress that add features or flags.




Comment at: clang-tools-extra/trunk/docs/ReleaseNotes.rst:55
 
-The improvements are...
+- :doc:`clang-doc ` now generates documentation in HTML format.
 

This should also include new flags and new features like template handling.



Comment at: clang-tools-extra/trunk/docs/clang-doc.rst:40
+
+  $ clang-doc /path/to/file.cpp -p /path/to/build
+

For this to work, you'd also need to pass the `--executor=standalone` flag.


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D65622/new/

https://reviews.llvm.org/D65622



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D65622: [clang-doc] Update documentation

2019-08-02 Thread Diego Astiazarán via Phabricator via cfe-commits 
This revision was automatically updated to reflect the committed changes.
Closed by commit rL367743: [clang-doc] Update documentation (authored by 
DiegoAstiazaran, committed by ).
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

Changed prior to commit:
  https://reviews.llvm.org/D65622?vs=213162=213165#toc

Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D65622/new/

https://reviews.llvm.org/D65622

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


Index: clang-tools-extra/trunk/docs/clang-doc.rst
===
--- clang-tools-extra/trunk/docs/clang-doc.rst
+++ clang-tools-extra/trunk/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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 @@
 -dump  - Dump intermediate results to bitcode file.
 -extra-arg=- Additional argument to append to the compiler 
command line
 -extra-arg-before= - Additional argument to prepend to the 
compiler command line
--omit-filenames- Omit filenames in output.
+--format=   - Format for outputted docs.
+  =yaml-   Documentation in YAML format.
+  =md  -   Documentation in MD format.
+  =html-   Documentation in HTML format.
 -output=   - Directory for outputting generated files.
 -p=- Build path
+--public   - Document only public declarations.
+--stylesheets= - CSS stylesheets to extend the default styles.
+
+``stylesheets`` should only be used if ``format`` is set to ``html``.
Index: clang-tools-extra/trunk/docs/ReleaseNotes.rst
===
--- clang-tools-extra/trunk/docs/ReleaseNotes.rst
+++ clang-tools-extra/trunk/docs/ReleaseNotes.rst
@@ -52,7 +52,7 @@
 Improvements to clang-doc
 -
 
-The improvements are...
+- :doc:`clang-doc ` now generates documentation in HTML format.
 
 Improvements to clang-query
 ---


Index: clang-tools-extra/trunk/docs/clang-doc.rst
===
--- clang-tools-extra/trunk/docs/clang-doc.rst
+++ clang-tools-extra/trunk/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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,

[PATCH] D65622: [clang-doc] Update documentation

2019-08-02 Thread Diego Astiazarán via Phabricator via cfe-commits 
DiegoAstiazaran updated this revision to Diff 213162.
DiegoAstiazaran added a comment.

Specify that `stylesheets` flag is only required for html format.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D65622/new/

https://reviews.llvm.org/D65622

Files:
  clang-tools-extra/docs/ReleaseNotes.rst
  clang-tools-extra/docs/clang-doc.rst


Index: clang-tools-extra/docs/clang-doc.rst
===
--- clang-tools-extra/docs/clang-doc.rst
+++ clang-tools-extra/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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 @@
 -dump  - Dump intermediate results to bitcode file.
 -extra-arg=- Additional argument to append to the compiler 
command line
 -extra-arg-before= - Additional argument to prepend to the 
compiler command line
--omit-filenames- Omit filenames in output.
+--format=   - Format for outputted docs.
+  =yaml-   Documentation in YAML format.
+  =md  -   Documentation in MD format.
+  =html-   Documentation in HTML format.
 -output=   - Directory for outputting generated files.
 -p=- Build path
+--public   - Document only public declarations.
+--stylesheets= - CSS stylesheets to extend the default styles.
+
+``stylesheets`` should only be used if ``format`` is set to ``html``.
Index: clang-tools-extra/docs/ReleaseNotes.rst
===
--- clang-tools-extra/docs/ReleaseNotes.rst
+++ clang-tools-extra/docs/ReleaseNotes.rst
@@ -52,7 +52,7 @@
 Improvements to clang-doc
 -
 
-The improvements are...
+- :doc:`clang-doc ` now generates documentation in HTML format.
 
 Improvements to clang-query
 ---


Index: clang-tools-extra/docs/clang-doc.rst
===
--- clang-tools-extra/docs/clang-doc.rst
+++ clang-tools-extra/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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

[PATCH] D65622: [clang-doc] Update documentation

2019-08-02 Thread Jake Ehrlich via Phabricator via cfe-commits 
jakehehrlich accepted this revision.
jakehehrlich added a comment.
This revision is now accepted and ready to land.

This looks fine to me


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D65622/new/

https://reviews.llvm.org/D65622



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D65622: [clang-doc] Update documentation

2019-08-02 Thread Eugene Zelenko via Phabricator via cfe-commits 
Eugene.Zelenko added inline comments.



Comment at: clang-tools-extra/docs/clang-doc.rst:93
+--public   - Document only public declarations.
+--stylesheets= - CSS stylesheets to extend the default styles.

It'll be reasonable to mention that this options make sense only for HTML 
output.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D65622/new/

https://reviews.llvm.org/D65622



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D65622: [clang-doc] Update documentation

2019-08-01 Thread Diego Astiazarán via Phabricator via cfe-commits 
DiegoAstiazaran created this revision.
DiegoAstiazaran added reviewers: jakehehrlich, juliehockett.
DiegoAstiazaran added a project: clang-tools-extra.

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


https://reviews.llvm.org/D65622

Files:
  clang-tools-extra/docs/ReleaseNotes.rst
  clang-tools-extra/docs/clang-doc.rst


Index: clang-tools-extra/docs/clang-doc.rst
===
--- clang-tools-extra/docs/clang-doc.rst
+++ clang-tools-extra/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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,11 @@
 -dump  - Dump intermediate results to bitcode file.
 -extra-arg=- Additional argument to append to the compiler 
command line
 -extra-arg-before= - Additional argument to prepend to the 
compiler command line
--omit-filenames- Omit filenames in output.
+--format=   - Format for outputted docs.
+  =yaml-   Documentation in YAML format.
+  =md  -   Documentation in MD format.
+  =html-   Documentation in HTML format.
 -output=   - Directory for outputting generated files.
 -p=- Build path
+--public   - Document only public declarations.
+--stylesheets= - CSS stylesheets to extend the default styles.
Index: clang-tools-extra/docs/ReleaseNotes.rst
===
--- clang-tools-extra/docs/ReleaseNotes.rst
+++ clang-tools-extra/docs/ReleaseNotes.rst
@@ -52,7 +52,7 @@
 Improvements to clang-doc
 -
 
-The improvements are...
+- :doc:`clang-doc ` now generates documentation in HTML format.
 
 Improvements to clang-query
 ---


Index: clang-tools-extra/docs/clang-doc.rst
===
--- clang-tools-extra/docs/clang-doc.rst
+++ clang-tools-extra/docs/clang-doc.rst
@@ -17,7 +17,7 @@
 there.
 
 Use
-=
+===
 
 :program:`clang-doc` is a `LibTooling
 `_-based tool, and so requires a
@@ -25,19 +25,42 @@
 see `How To Setup Tooling For LLVM
 `_).
 
-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