[PATCH] D153738: Add LibClang guide

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

In D153738#4484865 , @manuel5975p 
wrote:

> I guess manuel5975p (manuel.wink...@gmx.ch) would be nice

Thank you for the new documentation, it's really appreciated! I've landed this 
on your behalf in 12d72e4fdee91b3f1e314759d6aa33d25fb38f86 



Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

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

[PATCH] D153738: Add LibClang guide

[Aaron Ballman via Phabricator via cfe-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG12d72e4fdee9: Add libClang guide (authored by manuel5975p, 
committed by aaron.ballman).
Herald added a subscriber: arphaman.

Changed prior to commit:
  https://reviews.llvm.org/D153738?vs=538333=538655#toc

Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

Files:
  clang/docs/LibClang.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -65,6 +65,7 @@
ExternalClangExamples
IntroductionToTheClangAST
LibTooling
+   LibClang
LibFormat
ClangPlugins
RAVFrontendAction
Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,360 @@
+.. role:: raw-html(raw)
+:format: html
+
+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.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+
+  // file.cpp
+  struct foo{
+int bar;
+int* bar_pointer;
+  };
+
+.. code-block:: cpp
+
+  #include 
+  #include 
+
+  int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+  index,
+  "file.cpp", nullptr, 0,
+  nullptr, 0,
+  CXTranslationUnit_None); //Parse "file.cpp"
+
+
+if (unit == nullptr){
+  std::cerr << "Unable to parse translation unit. Quitting.\n";
+  return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+  }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+  clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+  CXString current_display_name = clang_getCursorDisplayName(current_cursor);
+  //Allocate a CXString representing the name of the current cursor
+
+  std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+  //Print the char* value of current_display_name
+
+  clang_disposeString(current_display_name);
+  //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+  //to all functions returning a CXString
+
+  return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return one of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block::
+
+  Visiting element foo
+  Visiting element bar
+  Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+
+- ``CXCursor_StructDecl``: A C or C++ struct.
+- ``CXCursor_FieldDecl``: A field in a struct, union, or C++ class.
+- ``CXCursor_CallExpr``: An expression that calls 

[PATCH] D153738: Add LibClang guide

[Manuel via Phabricator via cfe-commits]

manuel5975p added a comment.

I guess manuel5975p (manuel.wink...@gmx.ch) would be nice


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

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

[PATCH] D153738: Add LibClang guide

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

LGTM, thank you! Do you need me to commit this on your behalf? If so, what name 
and email address would you like me to use for patch attribution? (I'll build 
the docs locally and correct any remaining formatting mistakes before landing.)


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

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

[PATCH] D153738: Add LibClang guide

[Manuel via Phabricator via cfe-commits]

manuel5975p updated this revision to Diff 538333.

Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

Files:
  clang/docs/LibClang.rst

Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,364 @@
+.. role:: raw-html(raw)
+:format: html
+
+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.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+  
+  // file.cpp
+  struct foo{
+int bar;
+int* bar_pointer;
+  };
+
+.. code-block:: cpp
+  
+  #include 
+  #include 
+
+  int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+  index,
+  "file.cpp", nullptr, 0,
+  nullptr, 0,
+  CXTranslationUnit_None); //Parse "file.cpp"
+
+
+if (unit == nullptr){
+  std::cerr << "Unable to parse translation unit. Quitting.\n";
+  return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+  }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+  clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+  CXString current_display_name = clang_getCursorDisplayName(current_cursor); 
+  //Allocate a CXString representing the name of the current cursor
+  
+  std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+  //Print the char* value of current_display_name
+
+  clang_disposeString(current_display_name);
+  //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+  //to all functions returning a CXString
+
+  return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return one of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block:: 
+
+  Visiting element foo
+  Visiting element bar
+  Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+  
+- ``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.
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+A ``CXType`` represents a complete C++ type, including qualifiers and pointers. It has a member field ``CXTypeKind kind`` and additional opaque data.
+
+Example values for ``CXTypeKind kind``
+
+- ``CXType_Invalid``: Represents an invalid type (e.g., where no type is available)
+- ``CXType_Pointer``: A pointer to another type
+- ``CXType_Int``: Regular ``int``
+- ``CXType_Elaborated``: Represents a type that was referred to using an elaborated type 

[PATCH] D153738: Add LibClang guide

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

In D153738#4474602 , @manuel5975p 
wrote:

> Incorporate Aaron Ballman's corrections

Hmm, something seems to have gone sideways somewhere because it looks like none 
of the comments were addressed -- did you perhaps re-upload the original patch?


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

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

[PATCH] D153738: Add LibClang guide

[Manuel via Phabricator via cfe-commits]

manuel5975p updated this revision to Diff 537443.
manuel5975p marked 9 inline comments as done.
manuel5975p added a comment.

Incorporate Aaron Ballman's corrections


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

Files:
  clang/docs/LibClang.rst

Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,344 @@
+.. role:: raw-html(raw)
+:format: html
+
+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.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+~
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+  
+  // file.hpp
+  struct foo{
+int bar;
+int* bar_pointer;
+  };
+.. code-block:: cpp
+  
+  #include 
+  #include 
+
+  int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+  index,
+  "file.hpp", nullptr, 0,
+  nullptr, 0,
+  CXTranslationUnit_None); //Parse "file.hpp"
+
+
+if (unit == nullptr){
+  std::cerr << "Unable to parse translation unit. Quitting.\n";
+  return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+  }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+  clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+  CXString current_display_name = clang_getCursorDisplayName(current_cursor); 
+  //Allocate a CXString representing the name of the current cursor
+  
+  std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+  //Print the char* value of current_display_name
+
+  clang_disposeString(current_display_name);
+  //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+  //to all functions returning a CXString
+
+  return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return of of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block:: 
+
+  Visiting element foo
+  Visiting element bar
+  Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+  
+- ``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
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+``CXType`` is a struct with two members:
+
+.. code-block:: cpp
+
+  typedef struct {
+enum CXTypeKind kind;
+void *data[2];
+  } CXType;
+
+Example values for ``CXTypeKind kind``
+
+- ``CXType_Invalid``: Represents an invalid type (e.g., where no type is available)
+- ``CXType_Pointer``: A pointer to another type

[PATCH] D153738: Add LibClang guide

[Manuel via Phabricator via cfe-commits]

manuel5975p accepted this revision.
manuel5975p added a comment.
This revision is now accepted and ready to land.

Thanks a lot for carefully going through this. I will dispose of the 
documentation for CXType after accepting.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D153738

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

[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

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

[PATCH] D153738: Add LibClang guide

[Manuel via Phabricator via cfe-commits]

manuel5975p created this revision.
manuel5975p added a reviewer: aaron.ballman.
manuel5975p added projects: clang, clang-c.
Herald added a project: All.
manuel5975p requested review of this revision.
Herald added a subscriber: cfe-commits.

Add a libclang .rst file with some code examples, going over the most important 
types and functions of libclang.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D153738

Files:
  clang/docs/LibClang.rst

Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,344 @@
+.. role:: raw-html(raw)
+:format: html
+
+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.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+~
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+  
+  // file.hpp
+  struct foo{
+int bar;
+int* bar_pointer;
+  };
+.. code-block:: cpp
+  
+  #include 
+  #include 
+
+  int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+  index,
+  "file.hpp", nullptr, 0,
+  nullptr, 0,
+  CXTranslationUnit_None); //Parse "file.hpp"
+
+
+if (unit == nullptr){
+  std::cerr << "Unable to parse translation unit. Quitting.\n";
+  return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+  }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+  clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+  CXString current_display_name = clang_getCursorDisplayName(current_cursor); 
+  //Allocate a CXString representing the name of the current cursor
+  
+  std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+  //Print the char* value of current_display_name
+
+  clang_disposeString(current_display_name);
+  //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+  //to all functions returning a CXString
+
+  return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return of of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block:: 
+
+  Visiting element foo
+  Visiting element bar
+  Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+  
+- ``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
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+``CXType`` is a struct with two members:
+
+.. code-block:: cpp
+
+  typedef struct {
+enum CXTypeKind kind;
+void *data[2];
+  } CXType;
+
+Example values for ``CXTypeKind kind``
+
+-