Committed to branch dmalcolm/jit.
HTML built from this can be seen at:
https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs/internals/index.html#overview-of-code-structure
gcc/jit/ChangeLog.jit:
* docs/internals/index.rst ("Overview of code structure"): Add
more descriptive text, including various fragments of
internal-api.h as appropriate.
* internal-api.h: Add marker comments for use by "literalinclude"
directives in docs/internals/index.rst.
---
gcc/jit/ChangeLog.jit | 8 ++++++++
gcc/jit/docs/internals/index.rst | 28 ++++++++++++++++++++++++++++
gcc/jit/internal-api.h | 11 +++++++++++
3 files changed, 47 insertions(+)
diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit
index 3b33e0d..b4700e4 100644
--- a/gcc/jit/ChangeLog.jit
+++ b/gcc/jit/ChangeLog.jit
@@ -1,5 +1,13 @@
2014-09-24 David Malcolm <dmalc...@redhat.com>
+ * docs/internals/index.rst ("Overview of code structure"): Add
+ more descriptive text, including various fragments of
+ internal-api.h as appropriate.
+ * internal-api.h: Add marker comments for use by "literalinclude"
+ directives in docs/internals/index.rst.
+
+2014-09-24 David Malcolm <dmalc...@redhat.com>
+
* dummy-frontend.c (my_walker): Rename to...
(my_ggc_walker): ...this.
(my_root_tab): Rename to...
diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst
index 3702cad..c8b05e0 100644
--- a/gcc/jit/docs/internals/index.rst
+++ b/gcc/jit/docs/internals/index.rst
@@ -74,5 +74,33 @@ and once a test has been compiled, you can debug it directly:
Overview of code structure
--------------------------
+* ``libgccjit.c`` implements the API entrypoints. It performs error
+ checking, then calls into classes of the gcc::jit::recording namespace
+ within internal-api.c and internal-api.h.
+
+* The gcc::jit::recording classes (within ``internal-api.c`` and
+ ``internal-api.h``) record the API calls that are made:
+
+ .. literalinclude:: ../../internal-api.h
+ :start-after: /* Recording types. */
+ :end-before: /* End of recording types. */
+ :language: c++
+
+* When the context is compiled, the gcc::jit::playback classes (also
+ within ``internal-api.c`` and ``internal-api.h``) replay the API calls
+ within langhook:parse_file:
+
+ .. literalinclude:: ../../internal-api.h
+ :start-after: /* Playback types. */
+ :end-before: /* End of playback types. */
+ :language: c++
+
.. literalinclude:: ../../notes.txt
:lines: 1-
+
+Here is a high-level summary from ``internal-api.h``:
+
+ .. literalinclude:: ../../internal-api.h
+ :start-after: /* Summary. */
+ :end-before: namespace gcc {
+ :language: c++
diff --git a/gcc/jit/internal-api.h b/gcc/jit/internal-api.h
index 3a4717a..4603f21 100644
--- a/gcc/jit/internal-api.h
+++ b/gcc/jit/internal-api.h
@@ -38,6 +38,8 @@ along with GCC; see the file COPYING3. If not see
const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1;
+/* Summary. */
+
/* In order to allow jit objects to be usable outside of a compile
whilst working with the existing structure of GCC's code the
C API is implemented in terms of a gcc::jit::recording::context,
@@ -97,6 +99,9 @@ class result;
class dump;
namespace recording {
+
+ /* Recording types. */
+
/* Indentation indicates inheritance: */
class context;
class builtins_manager; // declared within jit-builtins.h
@@ -118,9 +123,13 @@ namespace recording {
class global;
class param;
class statement;
+
+ /* End of recording types. */
}
namespace playback {
+ /* Playback types. */
+
/* Indentation indicates inheritance: */
class context;
class wrapper;
@@ -135,6 +144,8 @@ namespace playback {
class source_file;
class source_line;
class location;
+
+ /* End of playback types. */
}
typedef playback::context replayer;
--
1.7.11.7
