doc: Make the necessity of flush/mark_dirty more obvious

src/cairo-surface.c

@@ -59,6 +59,38 @@
  * A cairo surface is created by using <firstterm>backend</firstterm>-specific
  * constructors, typically of the form
  * cairo_<emphasis>backend</emphasis>_surface_create().
+ *
+ * Most surface types allow accessing the surface without using Cairo
+ * functions. If you do this, keep in mind that it is mandatory that you call
+ * cairo_surface_flush() before reading from or writing to the surface and that
+ * you must use cairo_surface_mark_dirty() after modifying it.
+ * <example>
+ * <title>Directly modifying an image surface</title>
+ * <programlisting>
+ * void
+ * modify_image_surface (cairo_surface_t *surface)
+ * {
+ *   unsigned char *data;
+ *   int width, height, stride;
+ *
+ *   // flush to ensure all writing to the image was done
+ *   cairo_surface_flush (surface);
+ *
+ *   // modify the image
+ *   data = cairo_image_surface_get_data (surface);
+ *   width = cairo_image_surface_get_width (surface);
+ *   height = cairo_image_surface_get_height (surface);
+ *   stride = cairo_image_surface_get_stride (surface);
+ *   modify_image_data (data, width, height, stride);
+ *
+ *   // mark the image dirty so Cairo clears its caches.
+ *   cairo_surface_mark_dirty (surface);
+ * }
+ * </programlisting>
+ * </example>
+ * Note that for other surface types it might be necessary to acquire the
+ * surface's device first. See cairo_device_acquire() for a discussion of
+ * devices.
  */
 
 #define DEFINE_NIL_SURFACE(status, name)			\