Update documentation of cairo_paginated_surface

1 files changed, 12 insertions, 0 deletions

diff --git a/src/cairo-paginated-surface-private.h b/src/cairo-paginated-surface-private.h
index c18cb3c14..247ed7262 100644
--- a/src/cairo-paginated-surface-private.h
+++ b/src/cairo-paginated-surface-private.h
@@ -71,6 +71,18 @@ typedef struct _cairo_paginated_surface_backend {
  * have paginated output, (that is, things directed at printers, or
  * for saving content in files such as PostScript or PDF files).
  *
+ * To use the paginated surface, you'll first need to create your
+ * 'real' surface using _cairo_surface_init and the standard
+ * cairo_surface_backend_t. Then you also call
+ * _cairo_paginated_surface_create which takes its own, much simpler,
+ * cairo_paginated_surface_backend. You are free to return the result
+ * of _cairo_paginated_surface_create from your public
+ * cairo_<foo>_surface_create. The paginated backend will be careful
+ * to not let the user see that they really got a "wrapped"
+ * surface. See test-paginated-surface.c for a fairly minimal example
+ * of a paginated-using surface. That should be a reasonable example
+ * to follow.
+ *
  * What the paginated surface does is first save all drawing
  * operations for a page into a meta-surface. Then when the user calls
  * cairo_show_page, the paginated surface performs the following