[jit] Documentation tweaks

[David Malcolm <dmalcolm@redhat.com>]

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