[jit] Documentation tweaks

[David Malcolm]

Committed to branch dmalcolm/jit:

gcc/jit/ChangeLog.jit:
	* docs/internals/index.rst (Overview of code structure): Directly
	include the comment from jit-common.h as rst, rather than as a
	quoted C++ comment.
	* jit-common.h: Convert the summary format to valid reStructured
	text for inclusion by docs/internals/index.rst.
	* notes.txt: Clarify where libgccjit.c, jit-recording.c and
	jit-playback.c fit into the high-level diagram.
---
 gcc/jit/ChangeLog.jit            | 10 ++++++++++
 gcc/jit/docs/internals/index.rst |  7 +++----
 gcc/jit/jit-common.h             | 12 +++++++-----
 gcc/jit/notes.txt                | 13 +++++++++----
 4 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit
index 4592002..1a76543 100644
--- a/gcc/jit/ChangeLog.jit
+++ b/gcc/jit/ChangeLog.jit
@@ -1,5 +1,15 @@
 2014-10-07  David Malcolm  <dmalcolm@redhat.com>
 
+	* docs/internals/index.rst (Overview of code structure): Directly
+	include the comment from jit-common.h as rst, rather than as a
+	quoted C++ comment.
+	* jit-common.h: Convert the summary format to valid reStructured
+	text for inclusion by docs/internals/index.rst.
+	* notes.txt: Clarify where libgccjit.c, jit-recording.c and
+	jit-playback.c fit into the high-level diagram.
+
+2014-10-07  David Malcolm  <dmalcolm@redhat.com>
+
 	* Make-lang.in (jit_OBJS): Drop jit/internal-api.o.
 	Add jit/jit-recording.o and jit/jit-playback.o.
 
diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst
index 3065c60..1e3952c 100644
--- a/gcc/jit/docs/internals/index.rst
+++ b/gcc/jit/docs/internals/index.rst
@@ -152,7 +152,6 @@ Overview of code structure
 
 Here is a high-level summary from ``jit-common.h``:
 
-   .. literalinclude:: ../../jit-common.h
-    :start-after: /* Summary.  */
-    :end-before: namespace gcc {
-    :language: c++
+.. include:: ../../jit-common.h
+  :start-after: This comment is included by the docs.
+  :end-before: End of comment for inclusion in the docs.  */
diff --git a/gcc/jit/jit-common.h b/gcc/jit/jit-common.h
index 5c41ddd..58e4a8c 100644
--- a/gcc/jit/jit-common.h
+++ b/gcc/jit/jit-common.h
@@ -36,9 +36,9 @@ along with GCC; see the file COPYING3.  If not see
 
 const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1;
 
-/* Summary.  */
+/* This comment is included by the docs.
 
-/* In order to allow jit objects to be usable outside of a compile
+   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,
    which records the calls made to it.
@@ -79,15 +79,17 @@ const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1;
 
    During a playback, we associate objects from the recording with
    their counterparts during this playback.  For simplicity, we store this
-   within the recording objects, as "void *m_playback_obj", casting it to
+   within the recording objects, as ``void *m_playback_obj``, casting it to
    the appropriate playback object subclass.  For these casts to make
    sense, the two class hierarchies need to have the same structure.
 
-   Note that the playback objects that "m_playback_obj" points to are
+   Note that the playback objects that ``m_playback_obj`` points to are
    GC-allocated, but the recording objects don't own references:
    these associations only exist within a part of the code where
    the GC doesn't collect, and are set back to NULL before the GC can
-   run.  */
+   run.
+
+   End of comment for inclusion in the docs.  */
 
 namespace gcc {
 
diff --git a/gcc/jit/notes.txt b/gcc/jit/notes.txt
index 54dca8f..d337cb4 100644
--- a/gcc/jit/notes.txt
+++ b/gcc/jit/notes.txt
@@ -5,8 +5,13 @@ Client Code   . Generated .            libgccjit.so
    │          .           .          .               .
     ──────────────────────────>      .               .
               .           .    │     .               .
-
-              .       (record API calls)             .
+              .           .    V     .               .
+              .           .    ──> libgccjit.c       .
+              .           .        │ (error-checking).
+              .           .        │                 .
+              .           .        ──> jit-recording.c
+              .           .              (record API calls)
+              .           .    <───────              .
               .           .    │     .               .
    <───────────────────────────      .               .
    │          .           .          .               .
@@ -27,8 +32,8 @@ Client Code   . Generated .            libgccjit.so
               .           .          .    │          .
 ..........................................│..................VVVVVVVVVVVVV...
               .           .          .    │          .       No GC in here
-              .           .          .    │          .
-              .           .          .  (playback of API calls)
+              .           .          .    │ jit-playback.c
+              .           .          .    │   (playback of API calls)
               .           .          .    ───────────────> creation of functions,
               .           .          .               .     types, expression trees
               .           .          .    <──────────────── etc
-- 
1.7.11.7