diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index 789691065..fcf29144e 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -40,6 +40,44 @@
 
 G_BEGIN_DECLS
 
+/**
+ * SECTION:cogl-framebuffer
+ * @short_description: A common interface for manipulating framebuffers
+ *
+ * Framebuffers are a collection of buffers that can be rendered too.
+ * A framebuffer may be comprised of one or more color buffers, an
+ * optional depth buffer and an optional stencil buffer. Other
+ * configuration parameters are associated with framebuffers too such
+ * as whether the framebuffer supports multi-sampling (an anti-aliasing
+ * technique) or dithering.
+ *
+ * There are two kinds of framebuffer in Cogl, #CoglOnscreen
+ * framebuffers and #CoglOffscreen framebuffers. As the names imply
+ * offscreen framebuffers are for rendering something offscreen
+ * (perhaps to a texture which is bound as one of the color buffers).
+ * The exact semantics of onscreen framebuffers depends on the window
+ * system backend that you are using, but typically you can expect
+ * rendering to a #CoglOnscreen framebuffer will be immediately
+ * visible to the user.
+ *
+ * If you want to create a new framebuffer then you should start by
+ * looking at the #CoglOnscreen and #CoglOffscreen constructor
+ * functions, such as cogl_offscreen_new_to_texture() or
+ * cogl_onscreen_new(). The #CoglFramebuffer interface deals with
+ * all aspects that are common between those two types of framebuffer.
+ *
+ * Setup of a new CoglFramebuffer happens in two stages. There is a
+ * configuration stage where you specify all the options and ancillary
+ * buffers you want associated with your framebuffer and then when you
+ * are happy with the configuration you can "allocate" the framebuffer
+ * using cogl_framebuffer_allocate (). Technically explicitly calling
+ * cogl_framebuffer_allocate () is optional for convenience and the
+ * framebuffer will automatically be allocated when you first try to
+ * draw to it, but if you do the allocation manually then you can
+ * also catch any possible errors that may arise from your
+ * configuration.
+ */
+
 #ifdef COGL_ENABLE_EXPERIMENTAL_API
 #define cogl_onscreen_new cogl_onscreen_new_EXP
 
diff --git a/doc/reference/cogl-2.0-experimental/cogl-sections.txt b/doc/reference/cogl-2.0-experimental/cogl-sections.txt
index ce7934808..814a4390f 100644
--- a/doc/reference/cogl-2.0-experimental/cogl-sections.txt
+++ b/doc/reference/cogl-2.0-experimental/cogl-sections.txt
@@ -307,11 +307,48 @@ cogl_is_texture_3d
 <SECTION>
 <FILE>cogl-framebuffer</FILE>
 <TITLE>CoglFramebuffer: The Framebuffer Interface</TITLE>
+CoglFramebuffer
+COGL_FRAMEBUFFER
+cogl_framebuffer_allocate
+cogl_framebuffer_get_width
+cogl_framebuffer_get_height
+cogl_framebuffer_set_viewport
+cogl_framebuffer_get_viewport_x
+cogl_framebuffer_get_viewport_y
+cogl_framebuffer_get_viewport_width
+cogl_framebuffer_get_viewport_height
+cogl_framebuffer_get_viewport4fv
+cogl_framebuffer_get_red_bits
+cogl_framebuffer_get_green_bits
+cogl_framebuffer_get_blue_bits
+cogl_framebuffer_get_blue_bits
+cogl_framebuffer_swap_buffers
+cogl_framebuffer_swap_region
+cogl_framebuffer_add_swap_buffers_callback
+cogl_framebuffer_remove_swap_buffers_callback
+
+<SUBSECTION>
+cogl_get_draw_framebuffer
 cogl_set_framebuffer
 cogl_push_framebuffer
 cogl_pop_framebuffer
 </SECTION>
 
+<SECTION>
+<FILE>cogl-onscreen</FILE>
+<TITLE>CoglOnscreen: The Onscreen Framebuffer Interface</TITLE>
+CoglOnscreen
+COGL_ONSCREEN
+cogl_onscreen_x11_set_foreign_window_xid
+cogl_onscreen_x11_get_window_xid
+cogl_onscreen_x11_get_visual_xid
+cogl_onscreen_win32_set_foreign_window
+cogl_onscreen_win32_get_window
+cogl_onscreen_set_swap_throttled
+cogl_onscreen_show
+cogl_onscreen_hide
+</SECTION>
+
 <SECTION>
 <FILE>cogl-offscreen</FILE>
 <TITLE>Offscreen Framebuffers</TITLE>