diff --git a/TODO b/TODO
index dd08db4b..ca19f927 100644
--- a/TODO
+++ b/TODO
@@ -1,7 +1,9 @@
 
 - vips_object_unref_outputs() needs docs ... bindings will need it
  
+- copy-paste blog post about writing vips8 operations into 'extending'
 
+- vips_init() has a deprecation warning, bizarre
 
 
 - check and fix up docs
@@ -13,7 +15,7 @@
 
   need better vipsobject docs
 
-  gtk-doc now used markdown, phew, use this to expand some sections
+  gtk-doc now uses markdown, phew, use this to expand some sections
 
 
 
diff --git a/libvips/iofuncs/buffer.c b/libvips/iofuncs/buffer.c
index 4067bb5f..d5a6fd1a 100644
--- a/libvips/iofuncs/buffer.c
+++ b/libvips/iofuncs/buffer.c
@@ -584,9 +584,22 @@ vips__buffer_init_cb( VipsBufferThread *buffer_thread )
 {
 	/* This is a mem leak, not catastrophic.
 	 */
+
+	/* Threads (including the main thread) must call 
+	 * vips_thread_shutdown() before exiting. Check that they have.
+	 *
+	 * We can't save automatically, because the shutdown order is
+	 * important. We must free all memory before saving the thread
+	 * profile, for example.
+	 *
+	 * We can't do the freeing in this callback since GPrivate has already
+	 * stopped working. 
+	 */
+
 	vips_warn( "VipsBuffer", 
-		_( "vips_thread_shutdown() not called for thread %p" ),
-		g_thread_self() ); 
+		_( "vips_thread_shutdown() not called for thread %p, see %s" ),
+		g_thread_self(),
+		"https://github.com/jcupitt/ruby-vips/issues/55" ); 
 }
 
 /* Init the buffer cache system.
diff --git a/libvips/iofuncs/init.c b/libvips/iofuncs/init.c
index 3cf907e9..9c10910a 100644
--- a/libvips/iofuncs/init.c
+++ b/libvips/iofuncs/init.c
@@ -127,6 +127,9 @@ vips_get_argv0( void )
  * it may not be able to get hold of @argv0 and VIPS may therefore be unable
  * to find its data files. It is much better to call this function yourself.
  *
+ * vips_init() is a macro, since it tries to check binary compatibility
+ * between the caller and the library. 
+ *
  * vips_init() does approximately the following:
  *
  * <itemizedlist>
@@ -157,14 +160,14 @@ vips_get_argv0( void )
  * Example:
  *
  * |[
- * int main( int argc, char **argv )
+ * int main (int argc, char **argv)
  * {
- *   if( vips_init( argv[0] ) )
- *     vips_error_exit( "unable to start VIPS" );
+ *   if (vips_init (argv[0]))
+ *     vips_error_exit ("unable to start VIPS");
  *
- *   vips_shutdown();
+ *   vips_shutdown ();
  *
- *   return( 0 );
+ *   return 0;
  * }
  * ]|
  *
@@ -174,7 +177,7 @@ vips_get_argv0( void )
  * Returns: 0 on success, -1 otherwise
  */
 
-/* vips_init() is actually a macro which checks library and application
+/* vips_init() is a macro which checks library and application
  * compatibility before calling vips__init().
  */
 
diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c
index 589707e4..1e9c6f34 100644
--- a/libvips/iofuncs/type.c
+++ b/libvips/iofuncs/type.c
@@ -55,6 +55,16 @@
 #include <vips/internal.h>
 #include <vips/debug.h>
 
+/**
+ * SECTION: type
+ * @short_description: basic types
+ * @stability: Stable
+ * @see_also: <link linkend="libvips-operation">operation</link>
+ * @include: vips/vips.h
+ *
+ * A selection of GType defintions used by VIPS. 
+ */
+
 /* A very simple boxed type for testing. Just an int.
  */
 
diff --git a/libvips/iofuncs/vips.c b/libvips/iofuncs/vips.c
index 1bd52c65..ed80b20f 100644
--- a/libvips/iofuncs/vips.c
+++ b/libvips/iofuncs/vips.c
@@ -88,6 +88,21 @@
 #include <vips/internal.h>
 #include <vips/debug.h>
 
+/**
+ * SECTION: vips
+ * @short_description: startup, shutdown, version
+ * @stability: Stable
+ * @see_also: <link linkend="libvips-operation">operation</link>
+ * @include: vips/vips.h
+ *
+ * Start VIPS up, shut VIPS down, get version information, relocation. 
+ *
+ * VIPS is a relocatable package, meaning you can move the directory tree you
+ * compiled it to at runtime and it will still be able to find all data files.
+ * This is required for OS X and Windows, but slightly unusual in the Unix
+ * world. See vips_init() and vips_guess_prefix().
+ */
+
 /* Try to make an O_BINARY ... sometimes need the leading '_'.
  */
 #ifdef BINARY_OPEN