[cairo-commit] cairo/src cairo.c, 1.48, 1.49 cairo.h, 1.69, 1.70 cairo_font.c, 1.32, 1.33 cairo_ft_font.c, 1.38, 1.39 cairo_ps_surface.c, 1.18, 1.19 cairo_xlib_surface.c, 1.40, 1.41

[Owen Taylor]

Committed by: otaylor

Update of /cvs/cairo/cairo/src
In directory gabe:/tmp/cvs-serv14925/src

Modified Files:
	cairo.c cairo.h cairo_font.c cairo_ft_font.c 
	cairo_ps_surface.c cairo_xlib_surface.c 
Log Message:
2005-01-27  Owen Taylor  <otaylor at redhat.com>

        * src/cairo.[ch] src/cairo_font.c src/cairo_ft_font.c
        src/cairo_ps_surface.c src/cairo_xlib_surface.c: Move
        docs from docs/reference, with a fair bit of addition
        and rewriting.

        * doc/reference/: Remove old-format docs.

        * configure.in: Add a AC_PREREQ(2.54) (Jason Dorje Short)


Index: cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- cairo.c	27 Jan 2005 19:35:26 -0000	1.48
+++ cairo.c	27 Jan 2005 23:46:17 -0000	1.49
@@ -68,6 +68,18 @@
 #endif
 
 
+/**
+ * cairo_create:
+ * 
+ * Creates a new #cairo_t with default values. The target
+ * surface must be set on the #cairo_t with cairo_set_target_surface(),
+ * or a backend-specific function like cairo_set_target_image() before
+ * drawing with the #cairo_t.
+ * 
+ * Return value: a newly allocated #cairo_t with a reference
+ *  count of 1. The initial reference count should be released
+ *  with cairo_destroy() when you are done using the #cairo_t.
+ **/
 cairo_t *
 cairo_create (void)
 {
@@ -88,6 +100,14 @@
     return cr;
 }
 
+/**
+ * cairo_reference:
+ * @cr: a #cairo_t
+ * 
+ * Increases the reference count on @cr by one. This prevents
+ * @cr from being destroyed until a matching call to @cairo_destroy()
+ * is made.
+ **/
 void
 cairo_reference (cairo_t *cr)
 {
@@ -99,6 +119,14 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_destroy:
+ * @cr: a #cairo_t
+ * 
+ * Decreases the reference count on @cr by one. If the result
+ * is zero, then @cr and all associated resources are freed.
+ * See cairo_destroy().
+ **/
 void
 cairo_destroy (cairo_t *cr)
 {
@@ -117,6 +145,22 @@
     free (cr);
 }
 
+/**
+ * cairo_save:
+ * @cr: a #cairo_t
+ * 
+ * Makes a copy of the current state of @cr and saves it
+ * on an internal stack of saved states for @cr. When
+ * cairo_restore() is called, @cr will be restored to
+ * the saved state. Multiple calls to cairo_save() and
+ * cairo_restore() can be nested; each call to cairo_restore()
+ * restores the state from the matching paired cairo_save().
+ *
+ * It isn't necessary to clear all saved states before
+ * a #cairo_t is freed. If the reference count of a #cairo_t
+ * drops to zero in response to a call to cairo_destroy(),
+ * any saved states will be freed along with the #cairo_t.
+ **/
 void
 cairo_save (cairo_t *cr)
 {
@@ -144,6 +188,14 @@
 }
 slim_hidden_def(cairo_save);
 
+/**
+ * cairo_restore:
+ * @cr: a #cairo_t
+ * 
+ * Restores @cr to the state saved by a preceding call to
+ * cairo_save() and removes that state from the stack of
+ * saved states.
+ **/
 void
 cairo_restore (cairo_t *cr)
 {
@@ -170,6 +222,20 @@
 }
 slim_hidden_def(cairo_restore);
 
+/**
+ * cairo_copy:
+ * @dest: a #cairo_t
+ * @src: another #cairo_t
+ * 
+ * This function copies all current state information from src to
+ * dest. This includes the current point and path, the target surface,
+ * the transformation matrix, and so forth.
+ *
+ * The stack of states saved with cairo_save() is <emphasis>not</emphasis>
+ * not copied; nor are any saved states on @dest cleared. The
+ * operation only copies the current state of @src to the current
+ * state of @dest.
+ **/
 void
 cairo_copy (cairo_t *dest, cairo_t *src)
 {
@@ -216,6 +282,16 @@
 }
 */
 
+/**
+ * cairo_set_target_surface:
+ * @cr: a #cairo_t
+ * @surface: a #cairo_surface_t
+ * 
+ * Directs output for a #cairo_t to a given surface. The surface
+ * will be referenced by the #cairo_t, so you can immediately
+ * call cairo_surface_destroy() on it if you don't need to
+ * keep a reference to it around.
+ **/
 void
 cairo_set_target_surface (cairo_t *cr, cairo_surface_t *surface)
 {
@@ -228,6 +304,26 @@
 }
 slim_hidden_def(cairo_set_target_surface);
 
+/**
+ * cairo_set_target_image:
+ * @cr: a #cairo_t
+ * @data: a pointer to a buffer supplied by the application
+ *    in which to write contents.
+ * @format: the format of pixels in the buffer
+ * @width: the width of the image to be stored in the buffer
+ * @height: the eight of the image to be stored in the buffer
+ * @stride: the number of bytes between the start of rows
+ *   in the buffer. Having this be specified separate from @width
+ *   allows for padding at the end of rows, or for writing
+ *   to a subportion of a larger image.
+ * 
+ * Directs output for a #cairo_t to an in-memory image. The output
+ * buffer must be kept around until the #cairo_t is destroyed or set
+ * to to have a different target.  The initial contents of @buffer
+ * will be used as the inital image contents; you must explicitely
+ * clear the buffer, using, for example, cairo_rectangle() and
+ * cairo_fill() if you want it cleared.
+ **/
 void
 cairo_set_target_image (cairo_t		*cr,
 			char		*data,
@@ -268,6 +364,18 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_set_rgb_color:
+ * @cr: a #cairo_t
+ * @red: red component of color
+ * @green: green component of color
+ * @blue: blue component of color
+ * 
+ * Sets a constant color for filling and stroking. This replaces any
+ * pattern set with cairo_set_pattern(). The color components are
+ * floating point numbers in the range 0 to 1. If the values passed in
+ * are outside that range, they will be clamped.
+ **/
 void
 cairo_set_rgb_color (cairo_t *cr, double red, double green, double blue)
 {
@@ -301,6 +409,19 @@
     return _cairo_gstate_current_pattern (cr->gstate);
 }
 
+/**
+ * cairo_set_tolerance:
+ * @cr: a #cairo_t
+ * @tolerance: the tolerance, in device units (typically pixels)
+ * 
+ * Sets the tolerance used when converting paths into trapezoids.
+ * Curved segments of the path will be subdivided until the maximum
+ * deviation between the original path and the polygonal approximation
+ * is less than @tolerance. The default value is 0.1. A larger
+ * value will give better performance, a smaller value, better
+ * appearance. (Reducing the value from the default value of 0.1
+ * is unlikely to improve appearance significantly.)
+ **/
 void
 cairo_set_tolerance (cairo_t *cr, double tolerance)
 {
@@ -314,6 +435,17 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_set_alpha:
+ * @cr: a #cairo_t
+ * @alpha: the alpha value. 0 is transparent, 1 fully opaque.
+ *  if the value is outside the range 0 to 1, it will be
+ *  clamped to that range.
+ *     
+ * Sets an overall alpha value used for stroking and filling.  This
+ * value is multiplied with any alpha value coming from a gradient or
+ * image pattern.
+ **/
 void
 cairo_set_alpha (cairo_t *cr, double alpha)
 {
@@ -889,6 +1021,20 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_current_font:
+ * @cr: a #cairo_t
+ * 
+ * Gets the current font object for a #cairo_t. If there is no current
+ * font object, because the font parameters, transform, or target
+ * surface has been changed since a font was last used, a font object
+ * will be created and stored in in the #cairo_t.
+ *
+ * Return value: the current font object. Can return %NULL
+ *   on out-of-memory or if the context is already in
+ *   an error state. This object is owned by Cairo. To keep
+ *   a reference to it, you must call cairo_font_reference().
+ **/
 cairo_font_t *
 cairo_current_font (cairo_t *cr)
 {
@@ -916,6 +1062,22 @@
 }
 
 
+/**
+ * cairo_set_font:
+ * @cr: a #cairo_t
+ * @font: a #cairo_font_t
+ * 
+ * Replaces the current #cairo_font_t object in the #cairo_t with
+ * @font. The replaced font in the #cairo_t will be destroyed if there
+ * are no other references to it. Since a #cairo_font_t is specific to
+ * a particular output device and size, changing the transformation,
+ * font transformation, or target surfaces of a #cairo_t will clear
+ * any previously set font. Setting the font using cairo_set_font() is
+ * exclusive with the simple font selection API provided by
+ * cairo_select_font(). The size and transformation set by
+ * cairo_scale_font() and cairo_transform_font() are ignored unless
+ * they were taken into account when creating @font.
+ **/
 void
 cairo_set_font (cairo_t *cr, cairo_font_t *font)
 {

Index: cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -d -r1.69 -r1.70
--- cairo.h	27 Jan 2005 19:35:26 -0000	1.69
+++ cairo.h	27 Jan 2005 23:46:17 -0000	1.70
@@ -51,21 +51,32 @@
 CAIRO_BEGIN_DECLS
 
 /**
- * cairo_t
+ * cairo_t:
  *
  * A #cairo_t contains the current state of the rendering device,
  * including coordinates of yet to be drawn shapes.
  **/
 typedef struct _cairo cairo_t;
 
+/**
+ * cairo_surface_t:
+ *
+ * A #cairo_surface_t represents an image, either as the destination
+ * of a drawing operation or as source when drawing onto another
+ * surface. There are different subtypes of cairo_surface_t for
+ * different drawing backends; for example, cairo_image_surface_create()
+ * creates a bitmap image in memory.
+ *
+ * Memory management of #cairo_surface_t is done with
+ * cairo_surface_reference() and cairo_surface_destroy().
+ */
 typedef struct _cairo_surface cairo_surface_t;
 
 /**
- * cairo_t
+ * cairo_matrix_t:
  *
- * A <structname>cairo_matrix</structname> holds an affine
- * transformation, such as a scale, rotation, or shear, or a
- * combination of those.
+ * A #cairo_matrix_t holds an affine transformation, such as a scale,
+ * rotation, or shear, or a combination of those.
  **/
 typedef struct _cairo_matrix cairo_matrix_t;
 typedef struct _cairo_pattern cairo_pattern_t;
@@ -102,6 +113,28 @@
 void
 cairo_set_target_surface (cairo_t *cr, cairo_surface_t *surface);
 
+/**
+ * cairo_format_t
+ * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
+ *   alpha in the upper 8 bits, then red, then green, then blue.
+ *   The 32-bit quanties are stored native-endian. Pre-multiplied
+ *   alpha is used. (That is, 50% transparent red is 0x80800000,
+ *   not 0x80ff0000.)
+ * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
+ *   the upper 8 bits unused. Red, Green, and Blue are stored
+ *   in the remaining 24 bits in that order.
+ * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding
+ *   an alpha value.
+ * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding
+ *   an alpha value. Pixels are packed together into 32-bit
+ *   quantities. The ordering of the bits matches the
+ *   endianess of the platform. On a big-endian machine, the
+ *   first pixel is in the uppermost bit, on a little-endian
+ *   machine the first pixel is in the least-significant bit.
+ *
+ * #cairo_format_t is used to identify the memory format of
+ * image data.
+ */
 typedef enum cairo_format {
     CAIRO_FORMAT_ARGB32,
     CAIRO_FORMAT_RGB24,
@@ -170,6 +203,28 @@
 void
 cairo_set_tolerance (cairo_t *cr, double tolerance);
 
+/**
+ * cairo_full_rule_t
+ * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
+ * left-to-right, counts +1. If the path crosses the ray
+ * from right to left, counts -1. (Left and right are determined
+ * from the perspective of looking along the ray from the starting
+ * point.) If the total count is non-zero, the point will be filled.
+ *
+ * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
+ * intersections, without regard to the orientation of the contour. If
+ * the total number of intersections is odd, the point will be
+ * filled.
+ *
+ * #cairo_fill_rule_t is used to select how paths are filled. For both
+ * fill rules, whether or not a point is included in the fill is
+ * determined by taking a ray from that point to infinity and looking
+ * at intersections with the path. The ray can be in any direction,
+ * as long as it doesn't pass through the end point of a segment
+ * or have a tricky intersection such as intersecting tangent to the path.
+ * (Note that filling is not actually implemented in this way. This
+ * is just a description of the rule that is applied.)
+ **/
 typedef enum cairo_fill_rule {
     CAIRO_FILL_RULE_WINDING,
     CAIRO_FILL_RULE_EVEN_ODD
@@ -360,14 +415,75 @@
 
 /* Font/Text functions */
 
+/**
+ * cairo_font_t:
+ *
+ * A #cairo_font_t is a font scaled to a particular size and device
+ * resolution. A font can be set on a #cairo_t by using
+ * cairo_set_font() assuming that the current transformation and
+ * target surface of the #cairo_t match that for which the
+ * #cairo_font_t was created. The effect of using a mismatched
+ * #cairo_font_t will be incorrect font metrics.
+ */
 typedef struct _cairo_font cairo_font_t;
 
+/**
+ * cairo_glyph_t:
+ * @index: glyph index in the font. The exact interpretation of the
+ *      glyph index depends on the font technology being used.
+ * @x: the offset in the X direction between the origin used for
+ *     drawing or measuring the string and the origin of this glyph.
+ * @y: the offset in the Y direction between the origin used for
+ *     drawing or measuring the string and the origin of this glyph.
+ *
+ * The #cairo_glyph_t structure holds information about a single glyph
+ * when drawing or measuring text. A font is (in simple terms) a
+ * collection of shapes used to draw text. A glyph is one of these
+ * shapes. There can be multiple glyphs for a single character
+ * (alternates to be used in different contexts, for example), or a
+ * glyph can be a <firstterm>ligature</firstterm> of multiple
+ * characters. Cairo doesn't expose any way of converting input text
+ * into glyphs, so in order to use the Cairo interfaces that take
+ * arrays of glyphs, you must directly access the appropriate
+ * underlying font system.
+ *
+ * Note that the offsets given by @x and @y are not cumulative. When
+ * drawing or measuring text, each glyph is individually positioned
+ * with respect to the overall origin
+ **/
 typedef struct {
   unsigned long        index;
   double               x;
   double               y;
 } cairo_glyph_t;
 
+/**
+ * cairo_text_extents_t:
+ * @x_bearing: the horizontal distance from the origin to the
+ *   leftmost part of the glyphs as drawn. Positive if the
+ *   glyphs lie entirely to the right of the origin.
+ * @y_bearing: the vertical distance from the origin to the
+ *   topmost part of the glyphs as drawn. Positive only if the
+ *   glyphs lie completely below the origin; will usually be
+ *   negative.
+ * @width: width of the glyphs as drawn
+ * @height: height of the glyphs as drawn
+ * @x_advance:distance to advance in the X direction
+ *    after drawing these glyphs
+ * @y_advance: distance to advance in the Y direction
+ *   after drawing these glyphs. Will typically be zero except
+ *   for vertical text layout as found in East-Asian languages.
+ *
+ * The #cairo_text_extents_t< structure stores the extents of a single
+ * glyph or a string of glyphs in user-space coordinates. Because text
+ * extents are in user-space coordinates, they don't scale along with
+ * the current transformation matrix. If you call
+ * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
+ * be drawn twice as big, but the reported text extents will not be
+ * doubled. They will change slightly due to hinting (so you can't
+ * assume that metrics are independent of the transformation matrix),
+ * but otherwise will remain unchanged.
+ */
 typedef struct {
     double x_bearing;
     double y_bearing;

Index: cairo_font.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo_font.c,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -d -r1.32 -r1.33
--- cairo_font.c	27 Jan 2005 18:46:20 -0000	1.32
+++ cairo_font.c	27 Jan 2005 23:46:17 -0000	1.33
@@ -191,6 +191,19 @@
     font->backend->destroy_font (font);
 }
 
+/**
+ * cairo_font_glyph_extents:
+ * @font: a #cairo_font_t
+ * @font_matrix: the font transformation for which this font was
+ *    created. (See cairo_transform_font()). This is needed
+ *    properly convert the metrics from the font into user space.
+ * @glyphs: an array of glyph IDs with X and Y offsets.
+ * @num_glyphs: the number of glyphs in the @glyphs array
+ * @extents: a #cairo_text_extents_t which to store the retrieved extents.
+ * 
+ * cairo_font_glyph_extents() gets the overall metrics for a string of
+ * glyphs. The X and Y offsets in @glyphs are taken from an origin of 0,0. 
+ **/
 void
 cairo_font_glyph_extents (cairo_font_t          *font,
 			  cairo_matrix_t        *font_matrix,

Index: cairo_ft_font.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo_ft_font.c,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -d -r1.38 -r1.39
--- cairo_ft_font.c	27 Jan 2005 18:46:20 -0000	1.38
+++ cairo_ft_font.c	27 Jan 2005 23:46:17 -0000	1.39
@@ -1332,6 +1332,28 @@
 
 /* implement the platform-specific interface */
 
+/**
+ * cairo_ft_font_create:
+ * @pattern: A fully resolved fontconfig
+ *   pattern. A pattern can be resolved, by, among other things, calling
+ *   FcConfigSubstitute(), FcDefaultSubstitute(), then
+ *   FcFontMatch(). Cairo will call FcPatternReference() on this
+ *   pattern, so you should not further modify the pattern, but you can
+ *   release your reference to the pattern with FcPatternDestroy() if
+ *   you no longer need to access it.
+ * @scale: The scale at which this font will be used. The
+ *   scale is given by multiplying the font matrix (see
+ *   cairo_transform_font()) by the current transformation matrix.
+ *   The translation elements of the resulting matrix are ignored.
+ * 
+ * Creates a new font for the FreeType font backend based on a
+ * fontconfig pattern. This font can then be used with
+ * cairo_set_font(), cairo_font_glyph_extents(), or FreeType backend
+ * specific functions like cairo_ft_font_lock_face().
+ *
+ * Return value: a newly created #cairo_font_t. Free with
+ *  cairo_font_destroy() when you are done using it.
+ **/
 cairo_font_t *
 cairo_ft_font_create (FcPattern      *pattern,
 		      cairo_matrix_t *scale)
@@ -1347,6 +1369,32 @@
     return _ft_font_create (pattern, &sc);
 }
 
+/**
+ * cairo_ft_font_create_for_ft_face:
+ * @face: A FreeType face object, already opened. This must
+ *   be kept around until the font object's refcount drops to
+ *   zero and it is freed. The font object can be kept alive by
+ *   internal caching, so it's safest to keep the face object
+ *   around forever.
+ * @load_flags: The flags to pass to FT_Load_Glyph when loading
+ *   glyphs from the font. These flags control aspects of
+ *   rendering such as hinting and antialiasing. See the FreeType
+ *   docs for full information.
+ * @scale: The scale at which this font will be used. The
+ *   scale is given by multiplying the font matrix (see
+ *   cairo_transform_font()) by the current transformation matrix.
+ *   The translation elements of the resulting matrix are ignored.
+ * 
+ * Creates a new font forthe FreeType font backend from a pre-opened
+ * FreeType face. This font can then be used with cairo_set_font(),
+ * cairo_font_glyph_extents(), or FreeType backend specific
+ * functions like cairo_ft_font_lock_face() Cairo will determine the
+ * pixel size and transformation from the @scale parameter and call
+ * FT_Set_Transform() and FT_Set_Pixel_Sizes().
+ * 
+ * Return value: a newly created #cairo_font_t. Free with
+ *  cairo_font_destroy() when you are done using it.
+ **/
 cairo_font_t *
 cairo_ft_font_create_for_ft_face (FT_Face         face,
 				  int             load_flags,
@@ -1385,6 +1433,35 @@
 }
 
 
+/**
+ * cairo_ft_font_lock_face:
+ * @ft_font: A #cairo_font_t from the FreeType font backend. Such an
+ *   object can be created with cairo_ft_font_create() or
+ *   cairo_ft_font_create_for_ft_face(). On some platforms the font from
+ *   cairo_current_font() will also be a FreeType font, but using this
+ *   functionality with fonts you don't create yourself is not
+ *   recommended.
+ * 
+ * cairo_ft_font_lock_face() gets the #FT_Face object from a FreeType
+ * backend font and scales it appropriately for the font. You must
+ * release the face with cairo_ft_font_unlock_face()
+ * when you are done using it.  Since the #FT_Face object can be
+ * shared between multiple #cairo_font_t objects, you must not
+ * lock any other font objects until you unlock this one. A count is
+ * kept of the number of times cairo_ft_font_lock_face() is
+ * called. cairo_ft_font_unlock_face() must be called the same number
+ * of times.
+ *
+ * You must be careful when using this function in a library or in a
+ * threaded application, because other threads may lock faces that
+ * share the same #FT_Face object. For this reason, you must call
+ * cairo_ft_lock() before locking any face objects, and
+ * cairo_ft_unlock() after you are done. (These functions are not yet
+ * implemented, so this function cannot be currently safely used in a
+ * threaded application.)
+ 
+ * Return value: The #FT_Face object for @font, scaled appropriately.
+ **/
 FT_Face
 cairo_ft_font_lock_face (cairo_font_t *abstract_font)
 {
@@ -1400,6 +1477,18 @@
     return face;
 }
 
+/**
+ * cairo_ft_font_unlock_face:
+ * @ft_font: A #cairo_font_t from the FreeType font backend. Such an
+ *   object can be created with cairo_ft_font_create() or
+ *   cairo_ft_font_create_for_ft_face(). On some platforms the font from
+ *   cairo_current_font() will also be a FreeType font, but using this
+ *   functionality with fonts you don't create yourself is not
+ *   recommended.
+ * 
+ * Releases a face obtained with cairo_ft_font_lock_face(). See the
+ * documentation for that function for full details.
+ **/
 void
 cairo_ft_font_unlock_face (cairo_font_t *abstract_font)
 {
@@ -1408,6 +1497,24 @@
     _ft_unscaled_font_unlock_face (font->unscaled);
 }
 
+/**
+ * cairo_ft_font_get_pattern:
+ * @ft_font: A #cairo_font_t from the FreeType font backend. Such an
+ *   object can be created with cairo_ft_font_create() or
+ *   cairo_ft_font_create_for_ft_face(). On some platforms the font from
+ *   cairo_current_font() will also be a FreeType font, but using this
+ *   functionality with fonts you don't create yourself is not
+ *   recommended.
+ * 
+ * cairo_ft_font_get_pattern() gets the #FcPattern for a FreeType
+ * backend font. 
+
+ * Return value: The #FcPattenr for @font. The return value is owned
+ *   by the font, so you must not modify it, and must call
+ *   FcPatternReference() to keep a persistant reference to the
+ *   pattern. If the font was created with cairo_ft_font_create_for_ft_face()
+ *   returns %NULL.
+ **/
 FcPattern *
 cairo_ft_font_get_pattern (cairo_font_t *abstract_font)
 {

Index: cairo_ps_surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo_ps_surface.c,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- cairo_ps_surface.c	27 Jan 2005 18:46:20 -0000	1.18
+++ cairo_ps_surface.c	27 Jan 2005 23:46:17 -0000	1.19
@@ -42,6 +42,22 @@
 
 static const cairo_surface_backend_t cairo_ps_surface_backend;
 
+/**
+ * cairo_set_target_ps:
+ * @cr: a #cairo_t
+ * @file: an open, writeable file
+ * @width_inches: width of the output page, in inches
+ * @height_inches: height of the output page, in inches
+ * @x_pixels_per_inch: X resolution to use for image fallbacks;
+ *   not all Cairo drawing can be represented in a postscript
+ *   file, so Cairo will write out images for some portions
+ *   of the output.
+ * @y_pixels_per_inch: Y resolution to use for image fallbacks.
+ * 
+ * Directs output for a #cairo_t to a postscript file. The file must
+ * be kept open until the #cairo_t is destroyed or set to have a
+ * different target, and then must be closed by the application.
+ **/
 void
 cairo_set_target_ps (cairo_t	*cr,
 		     FILE	*file,

Index: cairo_xlib_surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo_xlib_surface.c,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -d -r1.40 -r1.41
--- cairo_xlib_surface.c	27 Jan 2005 18:46:20 -0000	1.40
+++ cairo_xlib_surface.c	27 Jan 2005 23:46:17 -0000	1.41
@@ -37,6 +37,22 @@
 #include "cairoint.h"
 #include "cairo-xlib.h"
 
+/**
+ * cairo_set_target_drawable:
+ * @cr: a #cairo_t
+ * @dpy: an X display
+ * @drawable: a window or pixmap on the default screen of @dpy
+ * 
+ * Directs output for a #cairo_t to an Xlib drawable.  @drawable must
+ * be a Window or Pixmap on the default screen of @dpy using the
+ * default colormap and visual.  Using this function is slow because
+ * the function must retrieve information about @drawable from the X
+ * server.
+ 
+ * The combination of cairo_xlib_surface_create() and
+ * cairo_set_target_surface() is somewhat more flexible, although
+ * it still is slow.
+ **/
 void
 cairo_set_target_drawable (cairo_t	*cr,
 			   Display	*dpy,