[jit] Flesh out the "Overview of code structure" in the docs

[David Malcolm]

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  <dmalcolm@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  <dmalcolm@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