document the RrSurfaceShape function

diff --git a/render2/render.h b/render2/render.h
index 53599d7e1dfa794c64026951ce6c2727cde820cf..30215e509dea9309d750cafe9ef4ef762a20feec 100644 (file)
--- a/render2/render.h
+++ b/render2/render.h
@@ -129,6 +129,14 @@ void RrSurfaceMinSize(struct RrSurface *sur,
                       int *w,
                       int *h);
 
+/*! Shape a surface to its children. This is not done implicitly inside the
+  library at *any* time. You must call this for each surface you want to
+  shape, when you want to update it. This means when you resize the surface
+  or change its base shape, or move/resize any of its children, you will need
+  to call this explicitly. Also, please note that you must call it on the
+  children surfaces first and work your way up to the top level surface for it
+  to function properly.
+*/
 void RrSurfaceShape(struct RrSurface *sur);
 
 /*! Set the base shape for a surface. To clear the base, pass 0 for all