Fix now-detected doc formatting issues

16 files changed, 51 insertions, 46 deletions

diff --git a/src/cairo-base85-stream.c b/src/cairo-base85-stream.c
index 2b8a8bee..88974039 100644
--- a/src/cairo-base85-stream.c
+++ b/src/cairo-base85-stream.c
@@ -1,4 +1,5 @@
-/* cairo_output_stream.c: Output stream abstraction
+/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
+/* cairo - a vector graphics library with display and print output
  *
  * Copyright © 2005 Red Hat, Inc
  *
diff --git a/src/cairo-beos-surface.cpp b/src/cairo-beos-surface.cpp
index 69dfd834..ec4aff03 100644
--- a/src/cairo-beos-surface.cpp
+++ b/src/cairo-beos-surface.cpp
@@ -946,7 +946,7 @@ _cairo_beos_surface_create_internal (BView*   view,
  * Creates a Cairo surface that draws onto a BeOS BView.
  * The caller must ensure that the view does not get deleted before the surface.
  * If the view is attached to a bitmap rather than an on-screen window, use
- * cairo_beos_surface_create_for_bitmap instead of this function.
+ * cairo_beos_surface_create_for_bitmap() instead of this function.
  **/
 cairo_surface_t *
 cairo_beos_surface_create (BView* view)
diff --git a/src/cairo-deflate-stream.c b/src/cairo-deflate-stream.c
index 9feb46de..bf2784a2 100644
--- a/src/cairo-deflate-stream.c
+++ b/src/cairo-deflate-stream.c
@@ -1,4 +1,5 @@
-/* cairo_deflate_stream.c: Output stream abstraction
+/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
+/* cairo - a vector graphics library with display and print output
  *
  * Copyright © 2006 Adrian Johnson
  *
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index 3e3f2a27..5824f49e 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -1,3 +1,4 @@
+/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
 /* cairo - a vector graphics library with display and print output
  *
  * Copyright © 2000 Keith Packard
diff --git a/src/cairo-meta-surface.c b/src/cairo-meta-surface.c
index 18a5b4b8..733ded4e 100644
--- a/src/cairo-meta-surface.c
+++ b/src/cairo-meta-surface.c
@@ -486,7 +486,7 @@ _cairo_meta_surface_show_glyphs (void			*abstract_surface,
  * surface-modifying function on the result of this function.
  *
  * The caller owns the return value and should call
- * cairo_surface_destroy when finished with it. This function will not
+ * cairo_surface_destroy() when finished with it. This function will not
  * return %NULL, but will return a nil surface instead.
  *
  * Return value: The snapshot surface.
diff --git a/src/cairo-os2-surface.c b/src/cairo-os2-surface.c
index f485cfe1..b0c27312 100644
--- a/src/cairo-os2-surface.c
+++ b/src/cairo-os2-surface.c
@@ -56,8 +56,8 @@
 
 /*
  * Here comes the extra API for the OS/2 platform. Currently it consists
- * of two extra functions, the cairo_os2_init () and the
- * cairo_os2_fini (). Both of them are called automatically if
+ * of two extra functions, the cairo_os2_init() and the
+ * cairo_os2_fini(). Both of them are called automatically if
  * Cairo is compiled to be a DLL file, but you have to call them before
  * using the Cairo API if you link to Cairo statically!
  *
diff --git a/src/cairo-output-stream-private.h b/src/cairo-output-stream-private.h
index 1a257881..9bfc5340 100644
--- a/src/cairo-output-stream-private.h
+++ b/src/cairo-output-stream-private.h
@@ -157,11 +157,11 @@ _cairo_memory_stream_copy (cairo_output_stream_t *base,
 cairo_private int
 _cairo_memory_stream_length (cairo_output_stream_t *stream);
 
-/* cairo_base85_stream.c */
+/* cairo-base85-stream.c */
 cairo_private cairo_output_stream_t *
 _cairo_base85_stream_create (cairo_output_stream_t *output);
 
-/* cairo_deflate_stream.c */
+/* cairo-deflate-stream.c */
 cairo_private cairo_output_stream_t *
 _cairo_deflate_stream_create (cairo_output_stream_t *output);
 
diff --git a/src/cairo-paginated-private.h b/src/cairo-paginated-private.h
index bb31487a..f2f80db3 100644
--- a/src/cairo-paginated-private.h
+++ b/src/cairo-paginated-private.h
@@ -80,7 +80,7 @@ struct _cairo_paginated_surface_backend {
  * _cairo_paginated_surface_create which takes its own, much simpler,
  * #cairo_paginated_surface_backend_t. 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
+ * 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
@@ -88,7 +88,7 @@ struct _cairo_paginated_surface_backend {
  *
  * 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
+ * cairo_show_page(), the paginated surface performs the following
  * sequence of operations (using the backend functions passed to
  * cairo_paginated_surface_create()):
  *
diff --git a/src/cairo-path-fixed.c b/src/cairo-path-fixed.c
index 58b3636f..90861198 100644
--- a/src/cairo-path-fixed.c
+++ b/src/cairo-path-fixed.c
@@ -872,11 +872,13 @@ _cairo_path_fixed_is_box (cairo_path_fixed_t *path,
 /*
  * Check whether the given path contains a single rectangle
  * that is logically equivalent to:
+ * <informalexample><programlisting>
  *   cairo_move_to (cr, x, y);
  *   cairo_rel_line_to (cr, width, 0);
  *   cairo_rel_line_to (cr, 0, height);
  *   cairo_rel_line_to (cr, -width, 0);
  *   cairo_close_path (cr);
+ * </programlisting></informalexample>
  */
 cairo_bool_t
 _cairo_path_fixed_is_rectangle (cairo_path_fixed_t *path,
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 27fe68dd..a20009b4 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -1156,7 +1156,7 @@ _cairo_surface_clone_similar (cairo_surface_t  *surface,
  * surface-modifying function on the result of this function.
  *
  * The caller owns the return value and should call
- * cairo_surface_destroy when finished with it. This function will not
+ * cairo_surface_destroy() when finished with it. This function will not
  * return %NULL, but will return a nil surface instead.
  *
  * Return value: The snapshot surface. Note that the return surface
diff --git a/src/cairo-unicode.c b/src/cairo-unicode.c
index 4ae5556e..caa4727d 100644
--- a/src/cairo-unicode.c
+++ b/src/cairo-unicode.c
@@ -1,4 +1,5 @@
-/* cairo_unicode.c: Unicode conversion routines
+/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
+/* cairo - a vector graphics library with display and print output
  *
  * The code in this file is derived from GLib's gutf8.c and
  *   ultimately from libunicode. It is relicensed under the
diff --git a/src/cairo-xcb-surface.c b/src/cairo-xcb-surface.c
index fbcb7f78..9bd9d72f 100644
--- a/src/cairo-xcb-surface.c
+++ b/src/cairo-xcb-surface.c
@@ -1856,7 +1856,7 @@ _cairo_xcb_screen_from_visual (xcb_connection_t *c, xcb_visualtype_t *visual)
  * by the provided visual.
  *
  * Note: If @drawable is a window, then the function
- * cairo_xcb_surface_set_size must be called whenever the size of the
+ * cairo_xcb_surface_set_size() must be called whenever the size of the
  * window changes.
  *
  * Return value: the newly created surface
@@ -1918,7 +1918,7 @@ cairo_xcb_surface_create_for_bitmap (xcb_connection_t     *c,
  * by the provided picture format.
  *
  * Note: If @drawable is a Window, then the function
- * cairo_xcb_surface_set_size must be called whenever the size of the
+ * cairo_xcb_surface_set_size() must be called whenever the size of the
  * window changes.
  *
  * Return value: the newly created surface.
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index b1069523..73975737 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -2353,7 +2353,7 @@ _cairo_xlib_screen_from_visual (Display *dpy, Visual *visual)
  * by the provided visual.
  *
  * Note: If @drawable is a Window, then the function
- * cairo_xlib_surface_set_size must be called whenever the size of the
+ * cairo_xlib_surface_set_size() must be called whenever the size of the
  * window changes.
  *
  * When @drawable is a Window containing child windows then drawing to
@@ -2419,7 +2419,7 @@ cairo_xlib_surface_create_for_bitmap (Display  *dpy,
  * by the provided picture format.
  *
  * Note: If @drawable is a Window, then the function
- * cairo_xlib_surface_set_size must be called whenever the size of the
+ * cairo_xlib_surface_set_size() must be called whenever the size of the
  * window changes.
  *
  * Return value: the newly created surface
diff --git a/src/cairo.c b/src/cairo.c
index 48bc58be..e001e70f 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -166,7 +166,7 @@ slim_hidden_def (cairo_version_string);
  * default values and with @target as a target surface. The target
  * surface should be constructed with a backend-specific function such
  * as cairo_image_surface_create() (or any other
- * cairo_<emphasis>backend</emphasis>_surface_create variant).
+ * cairo_<emphasis>backend</emphasis>_surface_create() variant).
  *
  * This function references @target, so you can immediately
  * call cairo_surface_destroy() on it if you don't need to
@@ -666,7 +666,7 @@ slim_hidden_def (cairo_set_operator);
  * clamped.
  *
  * The default source pattern is opaque black, (that is, it is
- * equivalent to cairo_set_source_rgb (cr, 0.0, 0.0, 0.0)).
+ * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
  **/
 void
 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
@@ -701,7 +701,7 @@ cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
  * will be clamped.
  *
  * The default source pattern is opaque black, (that is, it is
- * equivalent to cairo_set_source_rgba (cr, 0.0, 0.0, 0.0, 1.0)).
+ * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
  **/
 void
 cairo_set_source_rgba (cairo_t *cr,
@@ -785,7 +785,7 @@ slim_hidden_def (cairo_set_source_surface);
  * will not affect the source pattern. See cairo_pattern_set_matrix().
  *
  * The default source pattern is a solid pattern that is opaque black,
- * (that is, it is equivalent to cairo_set_source_rgb (cr, 0.0, 0.0,
+ * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
  * 0.0)).
  **/
 void
@@ -1449,7 +1449,7 @@ cairo_new_sub_path (cairo_t *cr)
  * will be (@x, @y).
  *
  * If there is no current point before the call to cairo_line_to()
- * this function will behave as cairo_move_to (@cr, @x, @y).
+ * this function will behave as cairo_move_to(@cr, @x, @y).
  **/
 void
 cairo_line_to (cairo_t *cr, double x, double y)
@@ -1487,7 +1487,7 @@ slim_hidden_def (cairo_line_to);
  *
  * If there is no current point before the call to cairo_curve_to()
  * this function will behave as if preceded by a call to
- * cairo_move_to (@cr, @x1, @y1).
+ * cairo_move_to(@cr, @x1, @y1).
  **/
 void
 cairo_curve_to (cairo_t *cr,
@@ -1669,7 +1669,7 @@ cairo_arc_to (cairo_t *cr,
  * by (@x, @y).
  *
  * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
- * is logically equivalent to cairo_move_to (@cr, x + @dx, y + @dy).
+ * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
  *
  * It is an error to call this function with no current point. Doing
  * so will cause @cr to shutdown with a status of
@@ -1706,7 +1706,7 @@ cairo_rel_move_to (cairo_t *cr, double dx, double dy)
  * current point will be offset by (@dx, @dy).
  *
  * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
- * is logically equivalent to cairo_line_to (@cr, x + @dx, y + @dy).
+ * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
  *
  * It is an error to call this function with no current point. Doing
  * so will cause @cr to shutdown with a status of
@@ -1749,10 +1749,9 @@ slim_hidden_def(cairo_rel_line_to);
  * (@dx2, @dy2) as the control points. After this call the current
  * point will be offset by (@dx3, @dy3).
  *
- * Given a current point of (x, y), cairo_rel_curve_to (@cr, @dx1,
+ * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
  * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
- * cairo_curve_to (@cr, x + @dx1, y + @dy1, x + @dx2, y + @dy2, x +
- * @dx3, y + @dy3).
+ * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
  *
  * It is an error to call this function with no current point. Doing
  * so will cause @cr to shutdown with a status of
@@ -2080,7 +2079,7 @@ cairo_mask_surface (cairo_t         *cr,
  *
  * A drawing operator that strokes the current path according to the
  * current line width, line join, line cap, and dash settings. After
- * cairo_stroke, the current path will be cleared from the cairo
+ * cairo_stroke(), the current path will be cleared from the cairo
  * context. See cairo_set_line_width(), cairo_set_line_join(),
  * cairo_set_line_cap(), cairo_set_dash(), and
  * cairo_stroke_preserve().
@@ -2702,7 +2701,7 @@ cairo_set_font_face (cairo_t           *cr,
  *
  * Return value: the current font face.  This object is owned by
  * cairo. To keep a reference to it, you must call
- * cairo_font_face_reference.
+ * cairo_font_face_reference().
  *
  * This function never returns %NULL. If memory cannot be allocated, a
  * special "nil" #cairo_font_face_t object will be returned on which
@@ -3015,7 +3014,7 @@ cairo_text_extents (cairo_t              *cr,
  * glyphs, (as they would be drawn by cairo_show_glyphs()).
  * Additionally, the x_advance and y_advance values indicate the
  * amount by which the current point would be advanced by
- * cairo_show_glyphs.
+ * cairo_show_glyphs().
  *
  * Note that whitespace glyphs do not contribute to the size of the
  * rectangle (extents.width and extents.height).
diff --git a/src/cairo.h b/src/cairo.h
index 63cf303f..762f9526 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1172,7 +1172,7 @@ cairo_font_face_status (cairo_font_face_t *font_face);
  *
  * The type of a font face is determined by the function used to
  * create it, which will generally be of the form
- * cairo_<emphasis>type</emphasis>_font_face_create. The font face type can be queried
+ * cairo_<emphasis>type</emphasis>_font_face_create(). The font face type can be queried
  * with cairo_font_face_get_type()
  *
  * The various #cairo_font_face_t functions can be used with a font face
@@ -1186,7 +1186,7 @@ cairo_font_face_status (cairo_font_face_t *font_face);
  * fonts of any type, but some font backends also provide
  * type-specific functions that must only be called with a scaled font
  * of the appropriate type. These functions have names that begin with
- * cairo_<emphasis>type</emphasis>_scaled_font such as cairo_ft_scaled_font_lock_face().
+ * cairo_<emphasis>type</emphasis>_scaled_font() such as cairo_ft_scaled_font_lock_face().
  *
  * The behavior of calling a type-specific function with a scaled font
  * of the wrong type is undefined.
@@ -1585,7 +1585,7 @@ cairo_surface_status (cairo_surface_t *surface);
  * any type, but some backends also provide type-specific functions
  * that must only be called with a surface of the appropriate
  * type. These functions have names that begin with
- * cairo_<emphasis>type</emphasis>_surface such as cairo_image_surface_get_width().
+ * cairo_<emphasis>type</emphasis>_surface<!-- --> such as cairo_image_surface_get_width().
  *
  * The behavior of calling a type-specific function with a surface of
  * the wrong type is undefined.
@@ -1820,7 +1820,7 @@ cairo_pattern_set_user_data (cairo_pattern_t		 *pattern,
  * The type of a pattern is determined by the function used to create
  * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
  * functions create SOLID patterns. The remaining
- * cairo_pattern_create functions map to pattern types in obvious
+ * cairo_pattern_create<!-- --> functions map to pattern types in obvious
  * ways.
  *
  * The pattern type can be queried with cairo_pattern_get_type()
diff --git a/src/cairoint.h b/src/cairoint.h
index 24e818b6..b52b0401 100755
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -237,7 +237,7 @@ _cairo_box_intersects_line_segment (cairo_box_t *box, cairo_line_t *line);
 cairo_private cairo_bool_t
 _cairo_box_contains_point (cairo_box_t *box, cairo_point_t *point);
 
-/* cairo_array.c structures and functions */
+/* cairo-array.c structures and functions */
 
 cairo_private void
 _cairo_array_init (cairo_array_t *array, int element_size);
@@ -943,7 +943,7 @@ _cairo_restrict_value (double *value, double min, double max);
 cairo_private int
 _cairo_lround (double d);
 
-/* cairo_gstate.c */
+/* cairo-gstate.c */
 cairo_private cairo_status_t
 _cairo_gstate_init (cairo_gstate_t  *gstate,
 		    cairo_surface_t *target);
@@ -1224,7 +1224,7 @@ _cairo_operator_bounded_by_mask (cairo_operator_t op);
 cairo_private cairo_bool_t
 _cairo_operator_bounded_by_source (cairo_operator_t op);
 
-/* cairo_color.c */
+/* cairo-color.c */
 cairo_private const cairo_color_t *
 _cairo_stock_color (cairo_stock_t stock);
 
@@ -1864,7 +1864,7 @@ _cairo_surface_set_device_scale (cairo_surface_t *surface,
 cairo_private cairo_bool_t
 _cairo_surface_has_device_transform (cairo_surface_t *surface);
 
-/* cairo_image_surface.c */
+/* cairo-image-surface.c */
 
 /* XXX: In cairo 1.2.0 we added a new %CAIRO_FORMAT_RGB16_565 but
  * neglected to adjust this macro. The net effect is that it's
@@ -1986,7 +1986,7 @@ _cairo_surface_is_image (const cairo_surface_t *surface);
 cairo_private cairo_bool_t
 _cairo_surface_is_meta (const cairo_surface_t *surface);
 
-/* cairo_pen.c */
+/* cairo-pen.c */
 cairo_private cairo_status_t
 _cairo_pen_init (cairo_pen_t	*pen,
 		 double		 radius,
@@ -2028,7 +2028,7 @@ _cairo_pen_stroke_spline (cairo_pen_t *pen,
 			  double tolerance,
 			  cairo_traps_t *traps);
 
-/* cairo_polygon.c */
+/* cairo-polygon.c */
 cairo_private void
 _cairo_polygon_init (cairo_polygon_t *polygon);
 
@@ -2050,7 +2050,7 @@ _cairo_polygon_line_to (cairo_polygon_t *polygon, cairo_point_t *point);
 cairo_private void
 _cairo_polygon_close (cairo_polygon_t *polygon);
 
-/* cairo_spline.c */
+/* cairo-spline.c */
 cairo_private cairo_int_status_t
 _cairo_spline_init (cairo_spline_t *spline,
 		    const cairo_point_t *a,
@@ -2064,7 +2064,7 @@ _cairo_spline_decompose (cairo_spline_t *spline, double tolerance);
 cairo_private void
 _cairo_spline_fini (cairo_spline_t *spline);
 
-/* cairo_matrix.c */
+/* cairo-matrix.c */
 cairo_private void
 _cairo_matrix_get_affine (const cairo_matrix_t *matrix,
 			  double *xx, double *yx,
@@ -2109,7 +2109,7 @@ cairo_private void
 _cairo_matrix_to_pixman_matrix (const cairo_matrix_t	*matrix,
 				pixman_transform_t	*pixman_transform);
 
-/* cairo_traps.c */
+/* cairo-traps.c */
 cairo_private void
 _cairo_traps_init (cairo_traps_t *traps);
 
@@ -2173,14 +2173,14 @@ _cairo_trapezoid_array_translate_and_scale (cairo_trapezoid_t *offset_traps,
 					    double tx, double ty,
 					    double sx, double sy);
 
-/* cairo_slope.c */
+/* cairo-slope.c */
 cairo_private void
 _cairo_slope_init (cairo_slope_t *slope, cairo_point_t *a, cairo_point_t *b);
 
 cairo_private int
 _cairo_slope_compare (cairo_slope_t *a, cairo_slope_t *b);
 
-/* cairo_pattern.c */
+/* cairo-pattern.c */
 
 cairo_private cairo_status_t
 _cairo_pattern_create_copy (cairo_pattern_t	  **pattern,
@@ -2273,7 +2273,7 @@ _cairo_gstate_get_antialias (cairo_gstate_t *gstate);
 
 #include "cairo-region-private.h"
 
-/* cairo_unicode.c */
+/* cairo-unicode.c */
 
 cairo_private cairo_status_t
 _cairo_utf8_to_ucs4 (const char *str,