[jit] Documentation tweaks

[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

[jit] Documentation tweaks

[David Malcolm]

Committed to branch dmalcolm/jit:

gcc/jit/ChangeLog.jit:
	* TODO.rst: Update.
	* docs/topics/expressions.rst (gcc_jit_context_new_call): Add
	a note clarifying the behavior of this entrypoint.
	* docs/topics/functions.rst (Creating and using functions): Markup
	fix.
	(gcc_jit_block_add_assignment_op): Add an example.
---
 gcc/jit/TODO.rst                    |  9 ++-------
 gcc/jit/docs/topics/expressions.rst | 23 +++++++++++++++++++++++
 gcc/jit/docs/topics/functions.rst   | 13 +++++++++++--
 3 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/gcc/jit/TODO.rst b/gcc/jit/TODO.rst
index c1ea024..09c4d9d 100644
--- a/gcc/jit/TODO.rst
+++ b/gcc/jit/TODO.rst
@@ -29,12 +29,6 @@ API
 
     gcc_jit_function_as_rvalue ()
 
-* clarify gcc_jit_function_add_eval()::
-
-    (void)expression;
-
-  and, indeed, clarify all of the other operations.
-
 * expressing branch probabilies (like __builtin_expect)::
 
     extern gcc_jit_rvalue *
@@ -99,7 +93,8 @@ Future milestones
 
 * Detect and issue warnings/errors about uses of uninitialized variables
 
-* Warn about unused objects in a context (e.g. rvalues/lvalues)?
+* Warn about unused objects in a context (e.g. rvalues/lvalues)?  (e.g.
+  for gcc_jit_context_new_call vs gcc_jit_block_add_eval)
 
 Nice to have
 ============
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 98d8e92..a95f5c9 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -364,6 +364,29 @@ Function calls
    Given a function and the given table of argument rvalues, construct a
    call to the function, with the result as an rvalue.
 
+   .. note::
+
+      :c:func:`gcc_jit_context_new_call` merely builds a
+      :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
+      perhaps as part of a more complicated expression.
+      The call *won't* happen unless you add a statement to a function
+      that evaluates the expression.
+
+      For example, if you want to call a function and discard the result
+      (or to call a function with ``void`` return type), use
+      :c:func:`gcc_jit_block_add_eval`:
+
+      .. code-block:: c
+
+         /* Add "(void)printf (arg0, arg1);".  */
+         gcc_jit_block_add_eval (
+           block, NULL,
+           gcc_jit_context_new_call (
+             ctxt,
+             NULL,
+             printf_func,
+             2, args));
+
 Type-coercion
 *************
 
diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst
index 15c895a..aa0c069 100644
--- a/gcc/jit/docs/topics/functions.rst
+++ b/gcc/jit/docs/topics/functions.rst
@@ -18,7 +18,7 @@
 .. default-domain:: c
 
 Creating and using functions
-================================
+============================
 
 Params
 ------
@@ -224,7 +224,16 @@ Statements
      lvalue *= rvalue;
      lvalue /= rvalue;
 
-   etc.
+   etc.  For example:
+
+   .. code-block:: c
+
+     /* "i++" */
+     gcc_jit_block_add_assignment_op (
+       loop_body, NULL,
+       i,
+       GCC_JIT_BINARY_OP_PLUS,
+       gcc_jit_context_one (ctxt, int_type));
 
 .. function:: void\
               gcc_jit_block_add_comment (gcc_jit_block *block,\
-- 
1.7.11.7