[Go] Updated Go documentation (examples, runtime.SetFinalizer, object ownership).

* Fixes swig/swig#266.
* Added links to working examples.
* Added link to runtime.SetFinalizer documentation.
* Added recommendation to read the runtime.SetFinalizer documentation before using it.
* Clarified that C++ objects ownership is not tracked and thus objects need to be freed manually.

Doc/Manual/Go.html

@@ -10,6 +10,7 @@
 <div class="sectiontoc">
 <ul>
 <li><a href="#Go_overview">Overview</a>
+<li><a href="#Go_examples">Examples</a>
 <li><a href="#Go_running_swig">Running SWIG with Go</a>
 <ul>
 <li><a href="#Go_commandline">Additional Commandline Options</a>
@@ -69,7 +70,18 @@ checking and runtime library are not used with Go.  This should be
 borne in mind when reading the rest of the SWIG documentation.
 </p>
 
-<H2><a name="Go_running_swig"></a>23.2 Running SWIG with Go</H2>
+<H2><a name="Go_examples"></a>23.2 Examples</H2>
+
+
+<p>
+Working examples can be found here:
+</p>
+<ul>
+<li><a href="https://github.com/golang/go/tree/master/misc/swig">Examples from the Go source tree</a>
+<li><a href="https://github.com/swig/swig/tree/master/Examples/go">Examples from the SWIG source tree</a>
+</ul>
+
+<H2><a name="Go_running_swig"></a>23.3 Running SWIG with Go</H2>
 
 
 <p>
@@ -78,7 +90,7 @@ default SWIG will generate code for the gc compilers.  To generate
 code for gccgo, you should also use the <tt>-gccgo</tt> option.
 </p>
 
-<H3><a name="Go_commandline"></a>23.2.1 Additional Commandline Options</H3>
+<H3><a name="Go_commandline"></a>23.3.1 Additional Commandline Options</H3>
 
 
 <p>
@@ -152,7 +164,7 @@ swig -go -help
 
 </table>
 
-<H3><a name="Go_outputs"></a>23.2.2 Go Output Files</H3>
+<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3>
 
 
 <p> When generating Go code, SWIG will generate the following
@@ -228,7 +240,7 @@ this:
 % go tool 6l main.6
 </pre></div>
 
-<H2><a name="Go_basic_tour"></a>23.3 A tour of basic C/C++ wrapping</H2>
+<H2><a name="Go_basic_tour"></a>23.4 A tour of basic C/C++ wrapping</H2>
 
 
 <p>
@@ -238,7 +250,7 @@ modifications have to occur.  This section briefly covers the
 essential aspects of this wrapping.
 </p>
 
-<H3><a name="Go_package"></a>23.3.1 Go Package Name</H3>
+<H3><a name="Go_package"></a>23.4.1 Go Package Name</H3>
 
 
 <p>
@@ -248,7 +260,7 @@ directive.  You may override this by using SWIG's <tt>-package</tt>
 command line option.
 </p>
 
-<H3><a name="Go_names"></a>23.3.2 Go Names</H3>
+<H3><a name="Go_names"></a>23.4.2 Go Names</H3>
 
 
 <p>
@@ -280,7 +292,7 @@ followed by that name, and the destructor will be
 named <tt>Delete</tt> followed by that name.
 </p>
 
-<H3><a name="Go_constants"></a>23.3.3 Go Constants</H3>
+<H3><a name="Go_constants"></a>23.4.3 Go Constants</H3>
 
 
 <p>
@@ -288,7 +300,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
 directive become Go constants, declared with a <tt>const</tt>
 declaration.
 
-<H3><a name="Go_enumerations"></a>23.3.4 Go Enumerations</H3>
+<H3><a name="Go_enumerations"></a>23.4.4 Go Enumerations</H3>
 
 
 <p>
@@ -298,7 +310,7 @@ usual).  The values of the enumeration will become variables in Go;
 code should avoid modifying those variables.
 </p>
 
-<H3><a name="Go_classes"></a>23.3.5 Go Classes</H3>
+<H3><a name="Go_classes"></a>23.4.5 Go Classes</H3>
 
 
 <p>
@@ -376,21 +388,24 @@ returns a go interface.  If the returned pointer can be null, you can check
 for this by calling the Swigcptr() method.
 </p>
 
-<H4><a name="Go_class_memory"></a>23.3.5.1 Go Class Memory Management</H4>
+<H4><a name="Go_class_memory"></a>23.4.5.1 Go Class Memory Management</H4>
 
 
 <p>
 Calling <tt>NewClassName</tt> for some C++ class <tt>ClassName</tt>
 will allocate memory using the C++ memory allocator.  This memory will
-not be automatically freed by Go's garbage collector.  When you are
+not be automatically freed by Go's garbage collector as the object ownership is
-done with the C++ object you must free it using <tt>DeleteClassName</tt>.
+not tracked.  When you are done with the C++ object you must free it manually
+using <tt>DeleteClassName</tt>.
 </p>
 
 <p>
 A common technique is to store the C++ object into a Go object, and
-use the Go function <tt>runtime.SetFinalizer</tt> to free the C++
+use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ object when
-object when the Go object is freed.  For example, if the SWIG package
+the Go object is freed. It is strongly recommended to read the
-is imported as "wrap":
+<a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer</a>
+documentation before using this technique to understand its limitations.
+For example, if the SWIG package is imported as "wrap":
 </p>
 <div class="code">
 <pre>
@@ -409,7 +424,7 @@ func NewGoClassName() *GoClassName {
 </pre>
 </div>
 
-<H4><a name="Go_class_inheritance"></a>23.3.5.2 Go Class Inheritance</H4>
+<H4><a name="Go_class_inheritance"></a>23.4.5.2 Go Class Inheritance</H4>
 
 
 <p>
@@ -421,7 +436,7 @@ Doing the reverse will require an explicit type assertion, which will
 be checked dynamically.
 </p>
 
-<H3><a name="Go_templates"></a>23.3.6 Go Templates</H3>
+<H3><a name="Go_templates"></a>23.4.6 Go Templates</H3>
 
 
 <p>
@@ -429,7 +444,7 @@ In order to use C++ templates in Go, you must tell SWIG to create
 wrappers for a particular template instantation.  To do this, use
 the <tt>%template</tt> directive.
 
-<H3><a name="Go_director_classes"></a>23.3.7 Go Director Classes</H3>
+<H3><a name="Go_director_classes"></a>23.4.7 Go Director Classes</H3>
 
 
 <p>
@@ -472,7 +487,7 @@ method defined in Go.  The Go code may of course call other methods on
 itself, and those methods may be defined either in Go or in C++.
 </p>
 
-<H3><a name="Go_primitive_type_mappings"></a>23.3.8 Default Go primitive type mappings</H3>
+<H3><a name="Go_primitive_type_mappings"></a>23.4.8 Default Go primitive type mappings</H3>
 
 
 <p>
@@ -579,7 +594,7 @@ that typemap, or add new values, to control how C/C++ types are mapped
 into Go types.
 </p>
 
-<H3><a name="Go_output_arguments"></a>23.3.9 Output arguments</H3>
+<H3><a name="Go_output_arguments"></a>23.4.9 Output arguments</H3>
 
 
 <p>Because of limitations in the way output arguments are processed in swig,
@@ -632,7 +647,7 @@ void f(char *output);
 </pre>
 </div>
 
-<H3><a name="Go_adding_additional_code"></a>23.3.10 Adding additional go code</H3>
+<H3><a name="Go_adding_additional_code"></a>23.4.10 Adding additional go code</H3>
 
 
 <p>Often the APIs generated by swig are not very natural in go, especially if
@@ -727,7 +742,7 @@ func bar() {
 </pre>
 </div>
 
-<H3><a name="Go_typemaps"></a>23.3.11 Go typemaps</H3>
+<H3><a name="Go_typemaps"></a>23.4.11 Go typemaps</H3>
 
 
 <p>