Documentation: C API comments

Review URL: https://codereview.chromium.org/1271023002

10 files changed, 443 insertions, 0 deletions

diff --git a/include/c/sk_canvas.h b/include/c/sk_canvas.h
index f65d3aa5c9..f6c0d4e1c1 100644
--- a/include/c/sk_canvas.h
+++ b/include/c/sk_canvas.h
@@ -15,29 +15,137 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Save the current matrix and clip on the canvas.  When the
+    balancing call to sk_canvas_restore() is made, the previous matrix
+    and clip are restored.
+*/
 SK_API void sk_canvas_save(sk_canvas_t*);
+/**
+    This behaves the same as sk_canvas_save(), but in addition it
+    allocates an offscreen surface. All drawing calls are directed
+    there, and only when the balancing call to sk_canvas_restore() is
+    made is that offscreen transfered to the canvas (or the previous
+    layer).
+
+    @param sk_rect_t* (may be null) This rect, if non-null, is used as
+                      a hint to limit the size of the offscreen, and
+                      thus drawing may be clipped to it, though that
+                      clipping is not guaranteed to happen. If exact
+                      clipping is desired, use sk_canvas_clip_rect().
+    @param sk_paint_t* (may be null) The paint is copied, and is applied
+                       to the offscreen when sk_canvas_restore() is
+                       called.
+*/
 SK_API void sk_canvas_save_layer(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
+/**
+    This call balances a previous call to sk_canvas_save() or
+    sk_canvas_save_layer(), and is used to remove all modifications to
+    the matrix and clip state since the last save call.  It is an
+    error to call sk_canvas_restore() more times than save and
+    save_layer were called.
+*/
 SK_API void sk_canvas_restore(sk_canvas_t*);
 
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified translation.
+*/
 SK_API void sk_canvas_translate(sk_canvas_t*, float dx, float dy);
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified scale.
+*/
 SK_API void sk_canvas_scale(sk_canvas_t*, float sx, float sy);
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified rotation in degrees.
+*/
 SK_API void sk_canvas_rotate_degrees(sk_canvas_t*, float degrees);
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified rotation in radians.
+*/
 SK_API void sk_canvas_rotate_radians(sk_canvas_t*, float radians);
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified skew.
+*/
 SK_API void sk_canvas_skew(sk_canvas_t*, float sx, float sy);
+/**
+    Preconcat the current coordinate transformation matrix with the
+    specified matrix.
+*/
 SK_API void sk_canvas_concat(sk_canvas_t*, const sk_matrix_t*);
 
+/**
+    Modify the current clip with the specified rectangle.  The new
+    current clip will be the intersection of the old clip and the
+    rectange.
+*/
 SK_API void sk_canvas_clip_rect(sk_canvas_t*, const sk_rect_t*);
+/**
+    Modify the current clip with the specified path.  The new
+    current clip will be the intersection of the old clip and the
+    path.
+*/
 SK_API void sk_canvas_clip_path(sk_canvas_t*, const sk_path_t*);
 
+/**
+    Fill the entire canvas (restricted to the current clip) with the
+    specified paint.
+*/
 SK_API void sk_canvas_draw_paint(sk_canvas_t*, const sk_paint_t*);
+/**
+    Draw the specified rectangle using the specified paint. The
+    rectangle will be filled or stroked based on the style in the
+    paint.
+*/
 SK_API void sk_canvas_draw_rect(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
+/**
+    Draw the specified oval using the specified paint. The oval will be
+    filled or framed based on the style in the paint
+*/
 SK_API void sk_canvas_draw_oval(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
+/**
+    Draw the specified path using the specified paint. The path will be
+    filled or framed based on the style in the paint
+*/
 SK_API void sk_canvas_draw_path(sk_canvas_t*, const sk_path_t*, const sk_paint_t*);
+/**
+    Draw the specified image, with its top/left corner at (x,y), using
+    the specified paint, transformed by the current matrix.
+
+    @param sk_paint_t* (may be NULL) the paint used to draw the image.
+*/
 SK_API void sk_canvas_draw_image(sk_canvas_t*, const sk_image_t*,
                                  float x, float y, const sk_paint_t*);
+/**
+    Draw the specified image, scaling and translating so that it fills
+    the specified dst rect. If the src rect is non-null, only that
+    subset of the image is transformed and drawn.
+
+    @param sk_paint_t* (may be NULL) The paint used to draw the image.
+*/
 SK_API void sk_canvas_draw_image_rect(sk_canvas_t*, const sk_image_t*,
                                       const sk_rect_t* src,
                                       const sk_rect_t* dst, const sk_paint_t*);
+
+/**
+    Draw the picture into this canvas (replay the pciture's drawing commands).
+
+    @param sk_matrix_t* If non-null, apply that matrix to the CTM when
+                        drawing this picture. This is logically
+                        equivalent to: save, concat, draw_picture,
+                        restore.
+
+    @param sk_paint_t* If non-null, draw the picture into a temporary
+                       buffer, and then apply the paint's alpha,
+                       colorfilter, imagefilter, and xfermode to that
+                       buffer as it is drawn to the canvas.  This is
+                       logically equivalent to save_layer(paint),
+                       draw_picture, restore.
+*/
 SK_API void sk_canvas_draw_picture(sk_canvas_t*, const sk_picture_t*,
                                    const sk_matrix_t*, const sk_paint_t*);
 
diff --git a/include/c/sk_data.h b/include/c/sk_data.h
index 95b7f5eb0b..90333bba5f 100644
--- a/include/c/sk_data.h
+++ b/include/c/sk_data.h
@@ -15,15 +15,54 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Returns a new empty sk_data_t.  This call must be balanced with a call to
+    sk_data_unref().
+*/
 SK_API sk_data_t* sk_data_new_empty();
+/**
+    Returns a new sk_data_t by copying the specified source data.
+    This call must be balanced with a call to sk_data_unref().
+*/
 SK_API sk_data_t* sk_data_new_with_copy(const void* src, size_t length);
+/**
+    Pass ownership of the given memory to a new sk_data_t, which will
+    call free() when the refernce count of the data goes to zero.  For
+    example:
+        size_t length = 1024;
+        void* buffer = malloc(length);
+        memset(buffer, 'X', length);
+        sk_data_t* data = sk_data_new_from_malloc(buffer, length);
+    This call must be balanced with a call to sk_data_unref().
+*/
 SK_API sk_data_t* sk_data_new_from_malloc(const void* memory, size_t length);
+/**
+    Returns a new sk_data_t using a subset of the data in the
+    specified source sk_data_t.  This call must be balanced with a
+    call to sk_data_unref().
+*/
 SK_API sk_data_t* sk_data_new_subset(const sk_data_t* src, size_t offset, size_t length);
 
+/**
+    Increment the reference count on the given sk_data_t. Must be
+    balanced by a call to sk_data_unref().
+*/
 SK_API void sk_data_ref(const sk_data_t*);
+/**
+    Decrement the reference count. If the reference count is 1 before
+    the decrement, then release both the memory holding the sk_data_t
+    and the memory it is managing.  New sk_data_t are created with a
+    reference count of 1.
+*/
 SK_API void sk_data_unref(const sk_data_t*);
 
+/**
+    Returns the number of bytes stored.
+*/
 SK_API size_t sk_data_get_size(const sk_data_t*);
+/**
+    Returns the pointer to the data.
+ */
 SK_API const void* sk_data_get_data(const sk_data_t*);
 
 SK_C_PLUS_PLUS_END_GUARD
diff --git a/include/c/sk_image.h b/include/c/sk_image.h
index e6f49b74ee..e90649d75d 100644
--- a/include/c/sk_image.h
+++ b/include/c/sk_image.h
@@ -30,12 +30,40 @@ SK_API sk_image_t* sk_image_new_raster_copy(const sk_imageinfo_t*, const void* p
  */
 SK_API sk_image_t* sk_image_new_from_encoded(const sk_data_t* encoded, const sk_irect_t* subset);
 
+/**
+ *  Encode the image's pixels and return the result as a new PNG in a
+ *  sk_data_t, which the caller must manage: call sk_data_unref() when
+ *  they are done.
+ *
+ *  If the image type cannot be encoded, this will return NULL.
+ */
 SK_API sk_data_t* sk_image_encode(const sk_image_t*);
 
+/**
+ *  Increment the reference count on the given sk_image_t. Must be
+ *  balanced by a call to sk_image_unref().
+*/
 SK_API void sk_image_ref(const sk_image_t*);
+/**
+ *  Decrement the reference count. If the reference count is 1 before
+ *  the decrement, then release both the memory holding the sk_image_t
+ *  and the memory it is managing.  New sk_image_t are created with a
+    reference count of 1.
+*/
 SK_API void sk_image_unref(const sk_image_t*);
+
+/**
+ *  Return the width of the sk_image_t/
+ */
 SK_API int sk_image_get_width(const sk_image_t*);
+/**
+ *  Return the height of the sk_image_t/
+ */
 SK_API int sk_image_get_height(const sk_image_t*);
+
+/**
+ *  Returns a non-zero value unique among all images.
+ */
 SK_API uint32_t sk_image_get_unique_id(const sk_image_t*);
 
 SK_C_PLUS_PLUS_END_GUARD
diff --git a/include/c/sk_maskfilter.h b/include/c/sk_maskfilter.h
index ce38605a85..5c22a06391 100644
--- a/include/c/sk_maskfilter.h
+++ b/include/c/sk_maskfilter.h
@@ -22,9 +22,24 @@ typedef enum {
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Increment the reference count on the given sk_maskfilter_t. Must be
+    balanced by a call to sk_maskfilter_unref().
+*/
 void sk_maskfilter_ref(sk_maskfilter_t*);
+/**
+    Decrement the reference count. If the reference count is 1 before
+    the decrement, then release both the memory holding the
+    sk_maskfilter_t and any other associated resources.  New
+    sk_maskfilter_t are created with a reference count of 1.
+*/
 void sk_maskfilter_unref(sk_maskfilter_t*);
 
+/**
+    Create a blur maskfilter.
+    @param sk_blurstyle_t The SkBlurStyle to use
+    @param sigma Standard deviation of the Gaussian blur to apply. Must be > 0.
+*/
 sk_maskfilter_t* sk_maskfilter_new_blur(sk_blurstyle_t, float sigma);
 
 SK_C_PLUS_PLUS_END_GUARD
diff --git a/include/c/sk_matrix.h b/include/c/sk_matrix.h
index 12d946547f..83f0122b00 100644
--- a/include/c/sk_matrix.h
+++ b/include/c/sk_matrix.h
@@ -15,14 +15,33 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/** Set the matrix to identity */
 void sk_matrix_set_identity(sk_matrix_t*);
 
+/** Set the matrix to translate by (tx, ty). */
 void sk_matrix_set_translate(sk_matrix_t*, float tx, float ty);
+/**
+    Preconcats the matrix with the specified translation.
+        M' = M * T(dx, dy)
+*/
 void sk_matrix_pre_translate(sk_matrix_t*, float tx, float ty);
+/**
+    Postconcats the matrix with the specified translation.
+        M' = T(dx, dy) * M
+*/
 void sk_matrix_post_translate(sk_matrix_t*, float tx, float ty);
 
+/** Set the matrix to scale by sx and sy. */
 void sk_matrix_set_scale(sk_matrix_t*, float sx, float sy);
+/**
+    Preconcats the matrix with the specified scale.
+        M' = M * S(sx, sy)
+*/
 void sk_matrix_pre_scale(sk_matrix_t*, float sx, float sy);
+/**
+    Postconcats the matrix with the specified scale.
+        M' = S(sx, sy) * M
+*/
 void sk_matrix_post_scale(sk_matrix_t*, float sx, float sy);
 
 SK_C_PLUS_PLUS_END_GUARD
diff --git a/include/c/sk_paint.h b/include/c/sk_paint.h
index 6699fb4f6f..e0886ad349 100644
--- a/include/c/sk_paint.h
+++ b/include/c/sk_paint.h
@@ -15,24 +15,78 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Create a new paint with default settings:
+        antialias : false
+        stroke : false
+        stroke width : 0.0f (hairline)
+        stroke miter : 4.0f
+        stroke cap : BUTT_SK_STROKE_CAP
+        stroke join : MITER_SK_STROKE_JOIN
+        color : opaque black
+        shader : NULL
+        maskfilter : NULL
+        xfermode_mode : SRCOVER_SK_XFERMODE_MODE
+*/
 SK_API sk_paint_t* sk_paint_new();
+/**
+    Release the memory storing the sk_paint_t and unref() all
+    associated objects.
+*/
 SK_API void sk_paint_delete(sk_paint_t*);
 
+/**
+    Return true iff the paint has antialiasing enabled.
+*/
 SK_API bool sk_paint_is_antialias(const sk_paint_t*);
+/**
+    Set to true to enable antialiasing, false to disable it on this
+    sk_paint_t.
+*/
 SK_API void sk_paint_set_antialias(sk_paint_t*, bool);
 
+/**
+    Return the paint's curent drawing color.
+*/
 SK_API sk_color_t sk_paint_get_color(const sk_paint_t*);
+/**
+    Set the paint's curent drawing color.
+*/
 SK_API void sk_paint_set_color(sk_paint_t*, sk_color_t);
 
 /* stroke settings */
 
+/**
+    Return true iff stroking is enabled rather than filling on this
+    sk_paint_t.
+*/
 SK_API bool sk_paint_is_stroke(const sk_paint_t*);
+/**
+    Set to true to enable stroking rather than filling with this
+    sk_paint_t.
+*/
 SK_API void sk_paint_set_stroke(sk_paint_t*, bool);
 
+/**
+    Return the width for stroking.  A value of 0 strokes in hairline mode.
+ */
 SK_API float sk_paint_get_stroke_width(const sk_paint_t*);
+/**
+   Set the width for stroking.  A value of 0 strokes in hairline mode
+   (always draw 1-pixel wide, regardless of the matrix).
+ */
 SK_API void sk_paint_set_stroke_width(sk_paint_t*, float width);
 
+/**
+    Return the paint's stroke miter value. This is used to control the
+    behavior of miter joins when the joins angle is sharp.
+*/
 SK_API float sk_paint_get_stroke_miter(const sk_paint_t*);
+/**
+   Set the paint's stroke miter value. This is used to control the
+   behavior of miter joins when the joins angle is sharp. This value
+   must be >= 0.
+*/
 SK_API void sk_paint_set_stroke_miter(sk_paint_t*, float miter);
 
 typedef enum {
@@ -41,7 +95,15 @@ typedef enum {
     SQUARE_SK_STROKE_CAP
 } sk_stroke_cap_t;
 
+/**
+    Return the paint's stroke cap type, controlling how the start and
+    end of stroked lines and paths are treated.
+*/
 SK_API sk_stroke_cap_t sk_paint_get_stroke_cap(const sk_paint_t*);
+/**
+    Set the paint's stroke cap type, controlling how the start and
+    end of stroked lines and paths are treated.
+*/
 SK_API void sk_paint_set_stroke_cap(sk_paint_t*, sk_stroke_cap_t);
 
 typedef enum {
@@ -50,7 +112,15 @@ typedef enum {
     BEVEL_SK_STROKE_JOIN
 } sk_stroke_join_t;
 
+/**
+    Return the paint's stroke join type, specifies the treatment that
+    is applied to corners in paths and rectangles
+ */
 SK_API sk_stroke_join_t sk_paint_get_stroke_join(const sk_paint_t*);
+/**
+    Set the paint's stroke join type, specifies the treatment that
+    is applied to corners in paths and rectangles
+ */
 SK_API void sk_paint_set_stroke_join(sk_paint_t*, sk_stroke_join_t);
 
 /**
diff --git a/include/c/sk_path.h b/include/c/sk_path.h
index d13a11219f..6b4e83d3b2 100644
--- a/include/c/sk_path.h
+++ b/include/c/sk_path.h
@@ -20,20 +20,56 @@ typedef enum {
     CCW_SK_PATH_DIRECTION,
 } sk_path_direction_t;
 
+/** Create a new, empty path. */
 SK_API sk_path_t* sk_path_new();
+/** Release the memory used by a sk_path_t. */
 SK_API void sk_path_delete(sk_path_t*);
 
+/** Set the beginning of the next contour to the point (x,y). */
 SK_API void sk_path_move_to(sk_path_t*, float x, float y);
+/**
+    Add a line from the last point to the specified point (x,y). If no
+    sk_path_move_to() call has been made for this contour, the first
+    point is automatically set to (0,0).
+*/
 SK_API void sk_path_line_to(sk_path_t*, float x, float y);
+/**
+    Add a quadratic bezier from the last point, approaching control
+    point (x0,y0), and ending at (x1,y1). If no sk_path_move_to() call
+    has been made for this contour, the first point is automatically
+    set to (0,0).
+*/
 SK_API void sk_path_quad_to(sk_path_t*, float x0, float y0, float x1, float y1);
+/**
+    Add a conic curve from the last point, approaching control point
+    (x0,y01), and ending at (x1,y1) with weight w.  If no
+    sk_path_move_to() call has been made for this contour, the first
+    point is automatically set to (0,0).
+*/
 SK_API void sk_path_conic_to(sk_path_t*, float x0, float y0, float x1, float y1, float w);
+/**
+    Add a cubic bezier from the last point, approaching control points
+    (x0,y0) and (x1,y1), and ending at (x2,y2). If no
+    sk_path_move_to() call has been made for this contour, the first
+    point is automatically set to (0,0).
+*/
 SK_API void sk_path_cubic_to(sk_path_t*,
                              float x0, float y0,
                              float x1, float y1,
                              float x2, float y2);
+/**
+   Close the current contour. If the current point is not equal to the
+   first point of the contour, a line segment is automatically added.
+*/
 SK_API void sk_path_close(sk_path_t*);
 
+/**
+    Add a closed rectangle contour to the path.
+*/
 SK_API void sk_path_add_rect(sk_path_t*, const sk_rect_t*, sk_path_direction_t);
+/**
+    Add a closed oval contour to the path
+*/
 SK_API void sk_path_add_oval(sk_path_t*, const sk_rect_t*, sk_path_direction_t);
 
 /**
diff --git a/include/c/sk_picture.h b/include/c/sk_picture.h
index f062d32e69..338b7d906a 100644
--- a/include/c/sk_picture.h
+++ b/include/c/sk_picture.h
@@ -15,16 +15,54 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Create a new sk_picture_recorder_t.  Its resources should be
+    released with a call to sk_picture_recorder_delete().
+*/
 sk_picture_recorder_t* sk_picture_recorder_new();
+/**
+    Release the memory and other resources used by this
+    sk_picture_recorder_t.
+*/
 void sk_picture_recorder_delete(sk_picture_recorder_t*);
 
+/**
+   Returns the canvas that records the drawing commands
+
+   @param sk_rect_t* the cull rect used when recording this
+                     picture. Any drawing the falls outside of this
+                     rect is undefined, and may be drawn or it may not.
+*/
 sk_canvas_t* sk_picture_recorder_begin_recording(sk_picture_recorder_t*, const sk_rect_t*);
+/**
+    Signal that the caller is done recording. This invalidates the
+    canvas returned by begin_recording. Ownership of the sk_picture_t
+    is passed to the caller, who must call sk_picture_unref() when
+    they are done using it.  The returned picture is immutable.
+*/
 sk_picture_t* sk_picture_recorder_end_recording(sk_picture_recorder_t*);
 
+/**
+    Increment the reference count on the given sk_picture_t. Must be
+    balanced by a call to sk_picture_unref().
+*/
 void sk_picture_ref(sk_picture_t*);
+/**
+    Decrement the reference count. If the reference count is 1 before
+    the decrement, then release both the memory holding the
+    sk_picture_t and any resouces it may be managing.  New
+    sk_picture_t are created with a reference count of 1.
+*/
 void sk_picture_unref(sk_picture_t*);
 
+/**
+    Returns a non-zero value unique among all pictures.
+ */
 uint32_t sk_picture_get_unique_id(sk_picture_t*);
+
+/**
+    Return the cull rect specified when this picture was recorded.
+*/
 sk_rect_t sk_picture_get_bounds(sk_picture_t*);
 
 SK_C_PLUS_PLUS_END_GUARD
diff --git a/include/c/sk_surface.h b/include/c/sk_surface.h
index f3c17d075d..d634185eec 100644
--- a/include/c/sk_surface.h
+++ b/include/c/sk_surface.h
@@ -15,10 +15,46 @@
 
 SK_C_PLUS_PLUS_BEGIN_GUARD
 
+/**
+    Return a new surface, with the memory for the pixels automatically
+    allocated.  If the requested surface cannot be created, or the
+    request is not a supported configuration, NULL will be returned.
+
+    @param sk_imageinfo_t* Specify the width, height, color type, and
+                           alpha type for the surface.
+
+    @param sk_surfaceprops_t* If not NULL, specify additional non-default
+                              properties of the surface.
+*/
 SK_API sk_surface_t* sk_surface_new_raster(const sk_imageinfo_t*, const sk_surfaceprops_t*);
+
+/**
+    Create a new surface which will draw into the specified pixels
+    with the specified rowbytes.  If the requested surface cannot be
+    created, or the request is not a supported configuration, NULL
+    will be returned.
+
+    @param sk_imageinfo_t* Specify the width, height, color type, and
+                           alpha type for the surface.
+    @param void* pixels Specify the location in memory where the
+                        destination pixels are.  This memory must
+                        outlast this surface.
+     @param size_t rowBytes Specify the difference, in bytes, between
+                           each adjacent row.  Should be at least
+                           (width * sizeof(one pixel)).
+    @param sk_surfaceprops_t* If not NULL, specify additional non-default
+                              properties of the surface.
+*/
 SK_API sk_surface_t* sk_surface_new_raster_direct(const sk_imageinfo_t*,
                                                   void* pixels, size_t rowBytes,
                                                   const sk_surfaceprops_t* props);
+
+/**
+    Decrement the reference count. If the reference count is 1 before
+    the decrement, then release both the memory holding the
+    sk_surface_t and any pixel memory it may be managing.  New
+    sk_surface_t are created with a reference count of 1.
+*/
 SK_API void sk_surface_unref(sk_surface_t*);
 
 /**
diff --git a/include/c/sk_types.h b/include/c/sk_types.h
index f6d73df94d..41dd2715b0 100644
--- a/include/c/sk_types.h
+++ b/include/c/sk_types.h
@@ -33,6 +33,7 @@ SK_C_PLUS_PLUS_BEGIN_GUARD
 
 typedef uint32_t sk_color_t;
 
+/* This macro assumes all arguments are >=0 and <=255. */
 #define sk_color_set_argb(a, r, g, b)   (((a) << 24) | ((r) << 16) | ((g) << 8) | (b))
 #define sk_color_get_a(c)               (((c) >> 24) & 0xFF)
 #define sk_color_get_r(c)               (((c) >> 16) & 0xFF)
@@ -65,6 +66,9 @@ typedef enum {
     BGR_V_SK_PIXELGEOMETRY,
 } sk_pixelgeometry_t;
 
+/**
+    Return the default sk_colortype_t; this is operating-system dependent.
+*/
 SK_API sk_colortype_t sk_colortype_get_default_8888();
 
 typedef struct {
@@ -101,15 +105,65 @@ typedef struct {
     float   mat[9];
 } sk_matrix_t;
 
+/**
+    A sk_canvas_t encapsulates all of the state about drawing into a
+    destination This includes a reference to the destination itself,
+    and a stack of matrix/clip values.
+*/
 typedef struct sk_canvas_t sk_canvas_t;
+/**
+    A sk_data_ holds an immutable data buffer.
+*/
 typedef struct sk_data_t sk_data_t;
+/**
+    A sk_image_t is an abstraction for drawing a rectagle of pixels.
+    The content of the image is always immutable, though the actual
+    storage may change, if for example that image can be re-created via
+    encoded data or other means.
+*/
 typedef struct sk_image_t sk_image_t;
+/**
+    A sk_maskfilter_t is an object that perform transformations on an
+    alpha-channel mask before drawing it; it may be installed into a
+    sk_paint_t.  Each time a primitive is drawn, it is first
+    scan-converted into a alpha mask, which os handed to the
+    maskfilter, which may create a new mask is to render into the
+    destination.
+ */
 typedef struct sk_maskfilter_t sk_maskfilter_t;
+/**
+    A sk_paint_t holds the style and color information about how to
+    draw geometries, text and bitmaps.
+*/
 typedef struct sk_paint_t sk_paint_t;
+/**
+    A sk_path_t encapsulates compound (multiple contour) geometric
+    paths consisting of straight line segments, quadratic curves, and
+    cubic curves.
+*/
 typedef struct sk_path_t sk_path_t;
+/**
+    A sk_picture_t holds recorded canvas drawing commands to be played
+    back at a later time.
+*/
 typedef struct sk_picture_t sk_picture_t;
+/**
+    A sk_picture_recorder_t holds a sk_canvas_t that records commands
+    to create a sk_picture_t.
+*/
 typedef struct sk_picture_recorder_t sk_picture_recorder_t;
+/**
+    A sk_shader_t specifies the source color(s) for what is being drawn. If a
+    paint has no shader, then the paint's color is used. If the paint
+    has a shader, then the shader's color(s) are use instead, but they
+    are modulated by the paint's alpha.
+*/
 typedef struct sk_shader_t sk_shader_t;
+/**
+    A sk_surface_t holds the destination for drawing to a canvas. For
+    raster drawing, the destination is an array of pixels in memory.
+    For GPU drawing, the destination is a texture or a framebuffer.
+*/
 typedef struct sk_surface_t sk_surface_t;
 
 typedef enum {