diff --git a/README.md b/README.md
index da42a581..a28f0098 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,9 @@ On Windows, you'll need to set the `RUBY_DLL_PATH` environment variable to
 point to the libvips bin directory.
 
 Take a look in `examples/`. There is [full API
-documentation](http://www.rubydoc.info/gems/ruby-vips). 
+documentation](http://www.rubydoc.info/gems/ruby-vips). The [`Vips` section
+has an introduction with
+examples](https://www.rubydoc.info/gems/ruby-vips/Vips).
 
 # Example
 
diff --git a/lib/vips.rb b/lib/vips.rb
index 03b8654a..e1e24eff 100644
--- a/lib/vips.rb
+++ b/lib/vips.rb
@@ -166,7 +166,7 @@ module GObject
 require 'vips/gvalue'
 
 # This module provides a binding for the [libvips image processing
-# library](https://jcupitt.github.io/libvips/).
+# library](https://libvips.github.io/libvips/).
 #
 # # Example
 #
@@ -404,12 +404,12 @@ module GObject
 # # Automatic YARD documentation
 #
 # The bulk of these API docs are generated automatically by
-# {Vips::generate_yard}. It examines
+# {Vips::Yard::generate}. It examines
 # libvips and writes a summary of each operation and the arguments and options
 # that that operation expects.
 #
 # Use the [C API
-# docs](https://jcupitt.github.io/libvips/API/current)
+# docs](https://libvips.github.io/libvips/API/current)
 # for more detail.
 #
 # # Enums
@@ -434,6 +434,43 @@ module GObject
 # If you want to avoid the copies, you'll need to call drawing operations
 # yourself.
 #
+# # Progress
+#
+# You can attach signal handlers to images to watch computation progress. For
+# example:
+#
+# ```ruby
+# image = Vips::Image.black 1, 100000
+# image.set_progress true
+# 
+# def progress_to_s(name, progress)
+#   puts "#{name}:"
+#   puts "    run = #{progress[:run]}"
+#   puts "    eta = #{progress[:eta]}"
+#   puts "    tpels = #{progress[:tpels]}"
+#   puts "    npels = #{progress[:npels]}"
+#   puts "    percent = #{progress[:percent]}"
+# end
+# 
+# image.signal_connect :preeval do |progress|
+#   progress_to_s("preeval", progress)
+# end
+# 
+# image.signal_connect :eval do |progress|
+#   progress_to_s("eval", progress)
+#   image.set_kill(true) if progress[:percent] > 50
+# end
+# 
+# image.signal_connect :posteval do |progress|
+#   progress_to_s("posteval", progress)
+# end
+# 
+# image.avg
+# ```
+# 
+# The `:eval` signal will fire for every tile that is processed. You can stop
+# progress with Image#set_kill and processing will end with an exception.
+#
 # # Overloads
 #
 # The wrapper defines the usual set of arithmetic, boolean and relational