Improve docs, with minor corrections and additions.

docs-src/application-lifecycle.md

@@ -1,5 +1,5 @@
 ## main thread
-The main function, and therefore the main loop,
+The `main` function, and therefore the main loop,
 should run on the main thread. 
 
 ```go
@@ -11,7 +11,7 @@ func init() {
 ```
 
 ## initialisation
-Call `gtk.Init` (or `gtk.InitChack`) before calling
+Call `gtk.Init` (or `gtk.InitCheck`) before calling
 any other gtk functions.
 Typically the program's command-line arguments will
 be passed to `gtk.Init`.
@@ -32,12 +32,14 @@ If an application has only one window,
 then it might terminate when the window is closed.
 
 ```go
+// Connect to the window's "destroy" signal.
 window.Widget().ConnectDestroy(func() {
     gtk.MainQuit()
 })
 ``` 
 
-This may be written more succinctly, like this.
+As the callback's signature matches that of `gtk.MainQuit`,
+this may be written more succinctly like this.
 
 ```go
 window.Widget().ConnectDestroy(gtk.MainQuit)

docs-src/build-tags.md

@@ -1,7 +1,7 @@
 gobbi uses Go 
 [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints)
 to allow targetting of specific library versions.
-This means that when using Go build tools
+This means that when using Go tools
 (such as `go build` and `go run`)
 to build a gobbi application,
 use of the `-tags` flag will usually be necessary.
@@ -26,6 +26,13 @@ is only available from gtk 3.10 onwards.
 So to use it, a tag specifying 3.10 (or a later version)
 is required.
 
+
+A tag such as `gtk_3.10` is formed of three parts.
+
+- the library name, `gtk`
+- an underscore, `_`
+- the minimum library version, `3.10`
+
 ```bash
 go build -tags gtk_3.10 my_app.go
 ```
@@ -55,6 +62,7 @@ The relevant setting is `Go: Build Tags`.
 ### goland
 In the `Settings...` dialog, the relevant setting can
 be found under
+
 - Go
-  - Vendoring & Build Tags
-    - Custom tags
+   - Vendoring & Build Tags
+      - Custom tags

docs-src/casting.md

@@ -1,6 +1,6 @@
 Gtk classes derive in a hierarchy from the GObject class.
 
-In gobbi's implementation of GOBject's classes,
+In gobbi's implementation of GObject's classes,
 each class does not directly extend
 (or embed in Go terms)
 its ancestor classes.
@@ -21,7 +21,7 @@ label := gtk.LabelNew("a label")
 window.Add(label)   // <-- ERROR
 ``` 
 
-`gtk.Window` does not directly have a `Add` method.
+`gtk.Window` does not directly have an `Add` method.
 The `Add` method is a member of `gtk.Container`,
 which is an ancestor of `gtk.Window`.
 
@@ -50,7 +50,7 @@ widget2 := gtk.WindowNew().Widget()
 
 # downcasting
 Downcasting operates in the other direction,
-from a class to a derived class,
+from a class to a derived class.
 
 Downcasting is less common that upcasting.
 It is potentially quite dangerous, in that it makes

docs-src/getting-started.md

@@ -4,7 +4,7 @@
     * debian/ubuntu packages -
         `libatk1.0-dev libcairo2-dev libglib2.0-dev
         libgtk-3-dev libpango1.0-dev`
-    * note that dev libraries are required because pkg-config
+    * note that dev versions of the libraries are required because pkg-config
         and headers are necessary
 * C compiler, and a linker
     * required because of the use of cgo
@@ -17,12 +17,15 @@
 * `./gobbi example simple_window`
     * Be patient.
         The first `go build` or `go run` will take quite a while,
-        perhaps a few minutes.
-        Subsequent builds of applications will be a *lot* quicker
-        as cached gobbi packages will be used by the Go commands. 
+        perhaps a minute.
+        Subsequent builds of applications will be a lot quicker
+        as cached gobbi packages will be used by the Go tools. 
 
 Run `./gobbi examples` for a list of the available examples.
 
+(The gobbi script supports other commands,
+but they are only needed for development of gobbi itself.)
+
 ## use in an application
 Using gobbi in an application in no different to using
 most other libraries.
@@ -38,6 +41,11 @@ Then import a package such as gtk.
 import "github.com/pekim/gobbi/lib/gtk"
 ```
 
+[Application lifecycle](application-lifecycle.html)
+describes the minimal apis needed to build
+an application that will create a window.
+
+
 ## build tags
 It will often be necessary to build gobbi applications
 with [build tags](../build-tags).

docs-src/goroutines.md

@@ -1,6 +1,6 @@
 All calls to gtk functions should be performed on
 the main thread.
-To perform such a call from a goroutine,
+To perform such calls from a goroutine,
 use `glib.IdleAdd` to schedule invocation of a
 callback function on the main thread. 
 

docs-src/gvalue.md

@@ -1,4 +1,5 @@
-The gobject library's `GValue` type is represented by
+The gobject library's `GValue` type is represented
+in gobbi by
 `gobject.Value`.
 
 See the [list](https://github.com/pekim/gobbi/blob/master/example/list/main.go)

docs-src/signal-handling.md

@@ -10,16 +10,21 @@ information.
 
 ```go
 button := gtk.ButtonNewWithLabel("a button")
+
+// enable emitting of motion events
 button.Widget().SetEvents(int32(gdk.GDK_POINTER_MOTION_MASK))
+
 button.Widget().ConnectMotionNotifyEvent(
     func(event *gdk.EventMotion) bool {
         fmt.Println(event.Y, event.Y)
         return false
-    })
+    }
+)
 ```
 
-Remember that it may be necessary to upcast to access the
-desired connect method.
+Remember that it may be necessary to
+[upcast](casting.html)
+to access the desired connect method.
 
 ## disconnecting
 All of the `Connect...` methods return a handler id.
@@ -36,26 +41,25 @@ The id may be used later to disconnect the handler.
 ```
 
 ## notify signal for a single property
-`ConnectNotifyProperty` connects the callback
+`ConnectNotifyProperty` connects a callback
 to the `notify` signal
 for a specific property of an Object.
 
-For example, to connect to the notify signal
-for the "title" property of a window.
+This is an example of connecting to the notify signal
+for a window's
+[title property](https://developer.gnome.org/gtk3/stable/GtkWindow.html#GtkWindow--title).
 
 ```go
     window := gtk.WindowNew(...)
 
+    // connect to the "notify::title" signal
     window.Object().ConnectNotifyProperty(
         "title", func(pspec *gobject.ParamSpec,
     ) {
         fmt.Println("title property changed")
     })
 ```
 
-In that example it is the `notify::title` signal
-that is being connected to.
-
 The returned value represents the connection,
 and may be passed to `DisconnectNotify` to remove it.
 

docs-src/variadic-functions.md

@@ -15,10 +15,13 @@ This is because `fmt.Sprint` is used to format a string
 before passing it as the last argument
 to the wrapped C function.
 
-A much simplified representation of such a function might
-help to make this clearer.
+A much simplified representation of such a
+gobbi function might help to make this clearer.
 ```go
-func SomeRepresentativeFunction(
+package gtk
+
+// a gobbi function
+func SomeFormatFunction(
 	a string, b int,
 	format string, args ...interface{},
 ) {
@@ -28,7 +31,17 @@ func SomeRepresentativeFunction(
 	formattedString := fmt.Sprintf(format, args...)
 	c_formattedString := C.String(formattedString)
 
-	C.some_representative_function(c_a, c_b, c_formattedString)
+	C.some_format_function(c_a, c_b, c_formattedString)
+}
+
+// ----------------------------- //
+
+// some application code
+func aFunction () {
+    gtk.SomeFormatFunction(
+        "a string", 123,
+        "the %s is %d", "answer", 42,
+    )
 }
 ```
 
@@ -38,7 +51,7 @@ because it would be impractical to automatically
 generate code that would support them.
 
 ### array functions
-In some cases there is another function that accepts an array
+In some cases there is an alternative function that accepts an array
 as the final argument instead.
 For example
 [gtk_list_store_new](https://developer.gnome.org/gtk3/stable/GtkListStore.html#gtk-list-store-new)
@@ -47,7 +60,7 @@ is not supported, but
 is supported as [gtk.ListStoreNewv](https://godoc.org/github.com/pekim/gobbi/lib/gtk#ListStoreNewv).
 
 ### multiple functions 
-There are other variadac functions that do not have an array
+There are other variadac functions that may not have an array
 equivalent version, but their functionality
 can be achieved through a combination of functions.