[PATCH, committed] jit documentation fixes

[PATCH, committed] jit documentation fixes

[David Malcolm]

On Thu, 2015-03-05 at 07:37 +0100, Bert Wesarg wrote:
> Hi David,
> 
> while reading the very good tutorial at
> 
> https://gcc.gnu.org/onlinedocs/jit/intro/tutorial03.html
> 
> I noticed that the calls to  gcc_jit_block_end_with_conditional()
> misses the on_true and on_false parameters.

Good catch, thanks!

This also affected the corresponding docs for the C++ bindings, and I
noticed a few other issues whilst re-reading the docs, so I've
committed the following patch to trunk (as r221218).

Dave

gcc/jit/ChangeLog:
	* docs/cp/intro/tutorial03.rst: Add missing arguments to
	gccjit::block::end_with_conditional call.  Add on_true/on_false
	comments.  Tweak the wording.
	* docs/intro/tutorial03.rst: Add missing arguments to
	gcc_jit_block_end_with_conditional call.  Add some clarifying
	comments.
	* docs/topics/compilation.rst: Tweak the wording to avoid an
	ambiguous use of "this".
	* docs/topics/contexts.rst: Fix a typo.
	* docs/topics/expressions.rst (GCC_JIT_BINARY_OP_MINUS): Remove
	a stray backtick.
---
 gcc/jit/docs/cp/intro/tutorial03.rst | 10 ++++++----
 gcc/jit/docs/intro/tutorial03.rst    | 12 +++++++++++-
 gcc/jit/docs/topics/compilation.rst  |  2 +-
 gcc/jit/docs/topics/contexts.rst     |  2 +-
 gcc/jit/docs/topics/expressions.rst  |  2 +-
 5 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/gcc/jit/docs/cp/intro/tutorial03.rst b/gcc/jit/docs/cp/intro/tutorial03.rst
index aac781d..f4405ad 100644
--- a/gcc/jit/docs/cp/intro/tutorial03.rst
+++ b/gcc/jit/docs/cp/intro/tutorial03.rst
@@ -238,7 +238,9 @@ and can then use this to add `b_loop_cond`'s sole statement, via
 
 .. code-block:: c++
 
-  b_loop_cond.end_with_conditional (guard);
+  b_loop_cond.end_with_conditional (guard,
+                                    b_after_loop, // on_true
+                                    b_loop_body); // on_false
 
 However :type:`gccjit::rvalue` has overloaded operators for this, so we
 express the conditional as
@@ -247,14 +249,14 @@ express the conditional as
 
    gccjit::rvalue guard = (i >= n);
 
-and hence write the block more concisely as:
+and hence we can write the block more concisely as:
 
 .. code-block:: c++
 
   b_loop_cond.end_with_conditional (
     i >= n,
-    b_after_loop,
-    b_loop_body);
+    b_after_loop, // on_true
+    b_loop_body); // on_false
 
 Next, we populate the body of the loop.
 
diff --git a/gcc/jit/docs/intro/tutorial03.rst b/gcc/jit/docs/intro/tutorial03.rst
index cd7136a..6c1ca3e 100644
--- a/gcc/jit/docs/intro/tutorial03.rst
+++ b/gcc/jit/docs/intro/tutorial03.rst
@@ -229,6 +229,7 @@ We build the comparison using :c:func:`gcc_jit_context_new_comparison`:
 
 .. code-block:: c
 
+  /* (i >= n) */
    gcc_jit_rvalue *guard =
      gcc_jit_context_new_comparison (
        ctxt, NULL,
@@ -241,7 +242,16 @@ and can then use this to add `b_loop_cond`'s sole statement, via
 
 .. code-block:: c
 
-  gcc_jit_block_end_with_conditional (b_loop_cond, NULL, guard);
+  /* Equivalent to:
+       if (guard)
+         goto after_loop;
+       else
+         goto loop_body;  */
+  gcc_jit_block_end_with_conditional (
+    b_loop_cond, NULL,
+    guard,
+    b_after_loop, /* on_true */
+    b_loop_body); /* on_false */
 
 Next, we populate the body of the loop.
 
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index 708d009..4eddf76 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -37,7 +37,7 @@ In-memory compilation
    This calls into GCC and builds the code, returning a
    `gcc_jit_result *`.
 
-   If this is non-NULL, the caller becomes responsible for
+   If the result is non-NULL, the caller becomes responsible for
    calling :func:`gcc_jit_result_release` on it once they're done
    with it.
 
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index 46a08bd..b7f281a 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -138,7 +138,7 @@ be responsible for all of the rest:
    If no errors occurred, this will be NULL.
 
 If you are wrapping the C API for a higher-level language that supports
-exception-handling, you may instead by interested in the last error that
+exception-handling, you may instead be interested in the last error that
 occurred on the context, so that you can embed this in an exception:
 
 .. function:: const char *\
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 1cedb66..49317b9 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -233,7 +233,7 @@ Binary Operation                          C equivalent
 
    For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
 
-.. c:macro:: GCC_JIT_BINARY_OP_MINUS`
+.. c:macro:: GCC_JIT_BINARY_OP_MINUS
 
    Subtraction of arithmetic values; analogous to:
 
-- 
1.8.5.3