[jit] Improvements to documentation.

[David Malcolm <dmalcolm@redhat.com>]

Committed to dmalcolm/jit branch.

gcc/jit/
	* libgccjit.h (gcc_jit_location): Rewrite comment to reflect
	that this part of the API is now implemented.
	("Functions for use within the code factory."): Add notes on
	memory-management and lifetimes.
	* notes.txt: Update diagram to show handle_locations.
---
 gcc/jit/ChangeLog.jit |  8 ++++++++
 gcc/jit/libgccjit.h   | 26 +++++++++++++++++---------
 gcc/jit/notes.txt     |  5 +++++
 3 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit
index 18101f1..da3e75a 100644
--- a/gcc/jit/ChangeLog.jit
+++ b/gcc/jit/ChangeLog.jit
@@ -1,5 +1,13 @@
 2013-10-15  David Malcolm  <dmalcolm@redhat.com>
 
+	* libgccjit.h (gcc_jit_location): Rewrite comment to reflect
+	that this part of the API is now implemented.
+	("Functions for use within the code factory."): Add notes on
+	memory-management and lifetimes.
+	* notes.txt: Update diagram to show handle_locations.
+
+2013-10-15  David Malcolm  <dmalcolm@redhat.com>
+
 	* TODO.rst: Update.
 
 2013-10-14  David Malcolm  <dmalcolm@redhat.com>
diff --git a/gcc/jit/libgccjit.h b/gcc/jit/libgccjit.h
index a17ab09..8985b8f 100644
--- a/gcc/jit/libgccjit.h
+++ b/gcc/jit/libgccjit.h
@@ -30,17 +30,17 @@ typedef struct gcc_jit_context gcc_jit_context;
 /* A gcc_jit_result encapsulates the result of a compilation.  */
 typedef struct gcc_jit_result gcc_jit_result;
 
-/* A gcc_jit_location will encapsulate a source code location, so that
-   you can associated locations in your language with statements in the
-   JIT-compiled code, allowing the debugger to single-step through
-   your language.
+/* A gcc_jit_location encapsulates a source code location, so that
+   you can (optionally) associate locations in your language with
+   statements in the JIT-compiled code, allowing the debugger to
+   single-step through your language.
 
-   This part of the API is a placeholder to allow future expansion
-   without breaking ABI: there currently is no way of creating a
-   gcc_jit_location.
+   Note that to do so, you also need to enable
+     GCC_JIT_BOOL_OPTION_DEBUGINFO
+   on the gcc_jit_context.
 
-   For now you must pass NULL into parameters expecting a
-   (gcc_jit_location *).  */
+   gcc_jit_location instances are optional; you can always pass
+   NULL.  */
 typedef struct gcc_jit_location gcc_jit_location;
 
 /* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*".  */
@@ -235,6 +235,14 @@ gcc_jit_result_release (gcc_jit_result *result);
 
 /**********************************************************************
  Functions for use within the code factory.
+
+ All objects created by these functions are cleaned up for you, after
+ your code-creation hook returns.  Note that this means you can't hold
+ references to them for use after you return from your callback.
+
+ All (const char *) string arguments passed to these functions are
+ copied, so you don't need to keep them around.  Note that this *isn't*
+ the case for other parts of the API.
  **********************************************************************/
 /* Creating source code locations for use by the debugger.
    Line and column numbers are 1-based.  */
diff --git a/gcc/jit/notes.txt b/gcc/jit/notes.txt
index 6d1288f..2c225ce 100644
--- a/gcc/jit/notes.txt
+++ b/gcc/jit/notes.txt
@@ -38,6 +38,11 @@ Client Code   . Generated .            libgccjit.so
        │etc   .           .          .               .
        │      .           .          .               .
        ──────────────────────────────────>           .
+Return from client callback          .    │          .
+              .           .          .    │          .
+              .           .          .    │(handle_locations: add locations to
+              .           .          .    │ linemap and associate them with trees)
+              .           .          .    │          .
               .           .          .    │          .       No GC in here
 ..........................................│..................AAAAAAAAAAAAA...
               .           .          .    │ for each function
-- 
1.7.11.7