[PATCH] D153738: Add LibClang guide

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

Thank you for adding this new documentation! In general, this is looking fantastic. Given how closely tied the C indexing APIs are with the rest of the compiler internals, I think it'd be helpful to add links to https://clang.llvm.org/docs/InternalsManual.html to various parts of this documentation to link the user back to more details. e.g., the section on source locations can link to https://clang.llvm.org/docs/InternalsManual.html#the-sourcelocation-and-sourcemanager-classes, etc. WDYT?



================
Comment at: clang/docs/LibClang.rst:4-5
+
+Libclang tutorial
+========================
+The C Interface to Clang provides a relatively small API that exposes facilities for parsing source code into an abstract syntax tree (AST), loading already-parsed ASTs, traversing the AST, associating physical source locations with elements within the AST, and other facilities that support Clang-based development tools.
----------------
Sphinx will complain if the underlines aren't the same length as what's being underlined.


================
Comment at: clang/docs/LibClang.rst:23-24
+
+CXCursor
+~~~~~~~~~~~~~~~~~
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
----------------



================
Comment at: clang/docs/LibClang.rst:33
+  
+  // file.hpp
+  struct foo{
----------------
Should we name this .cpp instead of .hpp? It's pretty weird to compile a header file, so using .cpp makes it clear that the TU is parsed as C++ code rather than as a header.


================
Comment at: clang/docs/LibClang.rst:37-38
+    int* bar_pointer;
+  };
+.. code-block:: cpp
+  
----------------
Pretty sure Sphinx will want a newline here.


================
Comment at: clang/docs/LibClang.rst:86
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return of of the three:
+
----------------



================
Comment at: clang/docs/LibClang.rst:114-116
+- ``CXCursor_StructDecl``: A C or C++ struct.
+- ``CXCursor_FieldDecl``: A field in a struct, union, or C++ class.
+- ``CXCursor_CallExpr``: An expression that calls a function
----------------
I noticed this in a few places -- you should make sure the punctuation is consistent for list elements.


================
Comment at: clang/docs/LibClang.rst:141-145
+``void* data[2]`` holds additional necessary type info, for example
+
+- Which struct was referred to?
+- What type is the pointer pointing to?
+- Qualifiers (e.g. ``const``, ``volatile``)?
----------------
I don't think we should document the `data` field in this way -- that's an implementation detail. Users should assume `data` is not something they can inspect or modify. Instead, users should use indexing APIs like `clang_equalTypes()`.


================
Comment at: clang/docs/LibClang.rst:150
+- ``clang_isConstQualifiedType`` to check for ``const``
+- ``clang_isRestrictQualifiedType`` to check for ``__restrict__``
+- ``clang_isVolatileQualifiedType`` to check for ``volatile``
----------------



================
Comment at: clang/docs/LibClang.rst:183
+
+The expected output of this program is
+
----------------



================
Comment at: clang/docs/LibClang.rst:260
+
+The expected output of this program is
+
----------------



Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738