GNOME.org
 

[gdk-pixbuf] Drop markup from doc comments

commit dabb77cf8fff1aa55c9e04362d849f775efb9551
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Feb 15 15:25:08 2014 -0500

    Drop markup from doc comments
    
    Switch to markdown for our inline markup needs, and
    turn off sgml mode for the docs.

 docs/reference/gdk-pixbuf/Makefile.am |    1 -
 gdk-pixbuf/gdk-pixbuf-io.c            |   71 ++++++++++++--------------------
 gdk-pixbuf/gdk-pixbuf-loader.c        |   61 +++++++++++-----------------
 gdk-pixbuf/gdk-pixbuf-scale.c         |   21 +++------
 gdk-pixbuf/gdk-pixbuf.c               |   35 ++++++----------
 gdk-pixbuf/gdk-pixdata.c              |   26 ++++++------
 6 files changed, 86 insertions(+), 129 deletions(-)
---
diff --git a/docs/reference/gdk-pixbuf/Makefile.am b/docs/reference/gdk-pixbuf/Makefile.am
index 61cfe49..71ac69b 100644
--- a/docs/reference/gdk-pixbuf/Makefile.am
+++ b/docs/reference/gdk-pixbuf/Makefile.am
@@ -45,7 +45,6 @@ GTKDOC_LIBS = \
 # Extra options to supply to gtkdoc-mkdb
 MKDB_OPTIONS= \
        --main-sgml-file=$(DOC_MAIN_SGML_FILE)  \
-       --sgml-mode                             \
        --source-dir=../../../contrib/gdk-pixbuf-xlib \
        --output-format=xml                     \
        --name-space=gdk_pixbuf
diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 426c0fd..bd17000 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -84,51 +84,39 @@
  * If GdkPixBuf has been compiled with GModule support, it can be extended by
  * modules which can load (and perhaps also save) new image and animation
  * formats. Each loadable module must export a
- * #GdkPixbufModuleFillInfoFunc function named <function>fill_info</function> and
+ * #GdkPixbufModuleFillInfoFunc function named `fill_info` and
  * a #GdkPixbufModuleFillVtableFunc function named
- * <function>fill_vtable</function>.
- * 
+ * `fill_vtable`.
  * 
  * In order to make format-checking work before actually loading the modules
  * (which may require dlopening image libraries), modules export their 
- * signatures (and other information) via the <function>fill_info</function>
- * function. An external utility, <command>gdk-pixbuf-query-loaders</command>, 
- * uses this to create a text file containing a list of all available loaders and 
- * their signatures. This file is then read at runtime by GdkPixBuf to obtain
- * the list of available loaders and their signatures. 
- * 
+ * signatures (and other information) via the `fill_info` function. An
+ * external utility, gdk-pixbuf-query-loaders, uses this to create a text
+ * file containing a list of all available loaders and  their signatures.
+ * This file is then read at runtime by GdkPixBuf to obtain the list of
+ * available loaders and their signatures. 
  * 
  * Modules may only implement a subset of the functionality available via
  * #GdkPixbufModule. If a particular functionality is not implemented, the
- * <function>fill_vtable</function> function will simply not set the corresponding
+ * `fill_vtable` function will simply not set the corresponding
  * function pointers of the #GdkPixbufModule structure. If a module supports
  * incremental loading (i.e. provides #begin_load, #stop_load and
  * #load_increment), it doesn't have to implement #load, since GdkPixBuf can
  * supply a generic #load implementation wrapping the incremental loading. 
  * 
- * 
  * Installing a module is a two-step process:
- * <itemizedlist>
- * <listitem><para>copy the module file(s) to the loader directory (normally
- * <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>,
- * unless overridden by the environment variable
- * <envar>GDK_PIXBUF_MODULEDIR</envar>) 
- * </para></listitem>
- * <listitem><para>call <command>gdk-pixbuf-query-loaders</command> to update the
- * module file (normally
- * <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>,
- * unless overridden by the environment variable
- * <envar>GDK_PIXBUF_MODULE_FILE</envar>)
- * </para></listitem>
- * </itemizedlist>
- * 
+ * - copy the module file(s) to the loader directory (normally
+ *   `$libdir/gtk-2.0/$version/loaders`, unless overridden by the
+ *   environment variable `GDK_PIXBUF_MODULEDIR`) 
+ * - call gdk-pixbuf-query-loaders to update the module file (normally
+ *   `$sysconfdir/gtk-2.0/gdk-pixbuf.loaders`, unless overridden by the
+ *   environment variable `GDK_PIXBUF_MODULE_FILE`)
  * 
  * The GdkPixBuf interfaces needed for implementing modules are contained in
- * <filename>gdk-pixbuf-io.h</filename> (and
- * <filename>gdk-pixbuf-animation.h</filename> if the module supports animations).
- * They are not covered by the same stability guarantees as the regular 
- * GdkPixBuf API. To underline this fact, they are protected by
- * <literal>#ifdef GDK_PIXBUF_ENABLE_BACKEND</literal>.
+ * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
+ * animations). They are not covered by the same stability guarantees as the
+ * regular  GdkPixBuf API. To underline this fact, they are protected by
+ * `#ifdef GDK_PIXBUF_ENABLE_BACKEND`.
  */
 
 
@@ -2235,10 +2223,9 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  * The variable argument list should be %NULL-terminated; if not empty,
  * it should contain pairs of strings that modify the save
  * parameters. For example:
- * <informalexample><programlisting>
- * gdk_pixbuf_save (pixbuf, handle, "jpeg", &amp;error,
- *                  "quality", "100", NULL);
- * </programlisting></informalexample>
+ * |[
+ * gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL);
+ * ]|
  *
  * Currently only few parameters exist. JPEG images can be saved with a
  * "quality" parameter; its value should be in the range [0,100].
@@ -2253,16 +2240,14 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  * The "icc-profile" value should be the complete ICC profile encoded
  * into base64.
  *
- * <informalexample><programlisting>
+ * |[
  * gchar *contents;
  * gchar *contents_encode;
  * gsize length;
  * g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL);
  * contents_encode = g_base64_encode ((const guchar *) contents, length);
- * gdk_pixbuf_save (pixbuf, handle, "png", &amp;error,
- *                  "icc-profile", contents_encode,
- *                  NULL);
- * </programlisting></informalexample>
+ * gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL);
+ * ]|
  *
  * TIFF images recognize a "compression" option which acceps an integer value.
  * Among the codecs are 1 None, 2 Huffman, 5 LZW, 7 JPEG and 8 Deflate, see
@@ -2274,7 +2259,6 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  *
  * Return value: whether an error was set
  **/
-
 gboolean
 gdk_pixbuf_save (GdkPixbuf  *pixbuf, 
                  const char *filename, 
@@ -3133,10 +3117,9 @@ _gdk_pixbuf_get_format (GdkPixbufModule *module)
  * by GdkPixbuf.
  *
  * Returns: (transfer container) (element-type GdkPixbufFormat): A list of
- * #GdkPixbufFormat<!-- -->s describing the supported
- * image formats.  The list should be freed when it is no longer needed,
- * but the structures themselves are owned by #GdkPixbuf and should not be
- * freed.
+ * #GdkPixbufFormats describing the supported image formats. The list should
+ * be freed when it is no longer needed, but the structures themselves are
+ * owned by #GdkPixbuf and should not be freed.
  *
  * Since: 2.2
  */
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 3518a01..edcc905 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -48,49 +48,38 @@
  * loading an extremely large file.
  * 
  * 
- * To use #GdkPixbufLoader to load an image, just create a new one,
- * and call gdk_pixbuf_loader_write() to send the data to it.  When
- * done, gdk_pixbuf_loader_close() should be called to end the stream
- * and finalize everything.  The loader will emit three important
- * signals throughout the process.  The first, "<link
- * linkend="GdkPixbufLoader-size-prepared">size_prepared</link>",
- * will be called as soon as the image has enough information to
+ * To use #GdkPixbufLoader to load an image, just create a new one, and
+ * call gdk_pixbuf_loader_write() to send the data to it.  When done,
+ * gdk_pixbuf_loader_close() should be called to end the stream and
+ * finalize everything. The loader will emit three important signals
+ * throughout the process. The first, #GdkPixbufLoader::size-prepared,
+ * will be emitted as soon as the image has enough information to
  * determine the size of the image to be used. If you want to scale
  * the image while loading it, you can call gdk_pixbuf_loader_set_size()
  * in response to this signal.
  * 
  * 
- * The second signal, "<link
- * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
- * will be called as soon as the pixbuf of the desired has been 
- * allocated.  You can obtain it by calling gdk_pixbuf_loader_get_pixbuf(). 
- * If you want to use it, simply ref it.  
- * In addition, no actual information will be passed in yet, so the
- * pixbuf can be safely filled with any temporary graphics (or an
- * initial color) as needed.  You can also call
- * gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf.
+ * The second signal, #GdkPixbufLoader::area-prepared, will be emitted as
+ * soon as the pixbuf of the desired has been allocated. You can obtain it
+ * by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply
+ * ref it.  In addition, no actual information will be passed in yet, so the
+ * pixbuf can be safely filled with any temporary graphics (or an initial
+ * color) as needed.  You can also call gdk_pixbuf_loader_get_pixbuf() later
+ * and get the same pixbuf.
  * 
+ * The last signal, #GdkPixbufLoader::area-updated, gets emitted every time
+ * a region is updated. This way you can update a partially completed image.
+ * Note that you do not know anything about the completeness of an image
+ * from the updated area. For example, in an interlaced image, you need to
+ * make several passes before the image is done loading.
  * 
- * The last signal, "<link
- * linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
- * called every time a region is updated.  This way you can update a
- * partially completed image.  Note that you do not know anything
- * about the completeness of an image from the area updated.  For
- * example, in an interlaced image, you need to make several passes
- * before the image is done loading.
- * 
- * 
- * <refsect2>
- * <title>Loading an animation</title>
- * <para>
- * Loading an animation is almost as easy as loading an
- * image. Once the first "<link
- * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" signal
- * has been emitted, you can call gdk_pixbuf_loader_get_animation()
- * to get the #GdkPixbufAnimation struct and gdk_pixbuf_animation_get_iter()
- * to get an #GdkPixbufAnimationIter for displaying it. 
- * </para>
- * </refsect2>
+ * # Loading an animation 
+ *
+ * Loading an animation is almost as easy as loading an image. Once the first
+ * #GdkPixbufLoader::area-prepared signal has been emitted, you can call
+ * gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct
+ * and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for
+ * displaying it. 
  */
 
 
diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c
index 89e2f66..acae7cd 100644
--- a/gdk-pixbuf/gdk-pixbuf-scale.c
+++ b/gdk-pixbuf/gdk-pixbuf-scale.c
@@ -52,7 +52,7 @@
  * with the Sun mediaLib library, these functions are instead accelerated
  * using mediaLib, which provides hardware acceleration on Intel, AMD,
  * and Sparc chipsets.  If desired, mediaLib support can be turned off by
- * setting the GDK_DISABLE_MEDIALIB environment variable.  
+ * setting the `GDK_DISABLE_MEDIALIB` environment variable.  
  * 
  * 
  * The following example demonstrates handling an expose event by
@@ -64,11 +64,9 @@
  * gdk_pixbuf_composite_color() function has exactly the same effect
  * as calling gdk_pixbuf_scale().
  * 
- * 
- * <example>
- * <title>Handling an expose event.</title>
- * <para>
- * <programlisting>
+ * ## Handling an expose event
+ *
+ * |[
  * gboolean
  * expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
  * {
@@ -93,9 +91,7 @@
  *   
  *   return TRUE;
  * }
- * </programlisting>
- * </para>
- * </example>
+ * ]|
  */
 
 
@@ -181,11 +177,8 @@ gdk_pixbuf_scale (const GdkPixbuf *src,
  * image, the data at the edges of the source image is replicated
  * to infinity. 
  *
- * <figure id="pixbuf-composite-diagram">
- *   <title>Compositing of pixbufs</title>
- *   <graphic fileref="composite.png" format="PNG"/>
- * </figure>
- **/
+ * ![](composite.png)
+ */
 void
 gdk_pixbuf_composite (const GdkPixbuf *src,
                      GdkPixbuf       *dest,
diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c
index c2c0219..6a907cc 100644
--- a/gdk-pixbuf/gdk-pixbuf.c
+++ b/gdk-pixbuf/gdk-pixbuf.c
@@ -53,19 +53,16 @@
  * in %NULL as the destroy notification function so that the data
  * will not be freed.
  * 
- * 
  * The gdk_pixbuf_new() function can be used as a convenience to
  * create a pixbuf with an empty buffer.  This is equivalent to
- * allocating a data buffer using <function>malloc()</function> and 
- * then wrapping it with gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() 
- * function will compute an optimal rowstride so that rendering can be 
- * performed with an efficient algorithm.
- * 
+ * allocating a data buffer using malloc() and then wrapping it with
+ * gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will
+ * compute an optimal rowstride so that rendering can be performed
+ * with an efficient algorithm.
  * 
  * As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
  * function to create a pixbuf from inline XPM image data.
  * 
- * 
  * You can also copy an existing pixbuf with the gdk_pixbuf_copy()
  * function.  This is not the same as just doing a g_object_ref()
  * on the old pixbuf; the copy function will actually duplicate the
@@ -87,14 +84,11 @@
  * its reference count drops to zero.  Newly-created #GdkPixbuf
  * structures start with a reference count of one.
  * 
+ * > As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and
+ * > gdk_pixbuf_unref() are deprecated in favour of g_object_ref()
+ * > and g_object_unref() resp.
  * 
- * <note>
- * As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and
- * gdk_pixbuf_unref() are deprecated in favour of g_object_ref()
- * and g_object_unref () resp.
- * </note>
- * 
- * <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
+ * Finalizing a pixbuf means to free its pixel
  * data and to free the #GdkPixbuf structure itself.  Most of the
  * library functions that create #GdkPixbuf structures create the
  * pixel data by themselves and define the way it should be freed;
@@ -621,8 +615,8 @@ gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf)
  * Queries a pointer to the pixel data of a pixbuf.
  *
  * Return value: (array): A pointer to the pixbuf's pixel data.
- * Please see <xref linkend="image-data"/> for information about how
- * the pixel data is stored in memory.
+ * Please see the section on [image data](image-data) for information
+ * about how the pixel data is stored in memory.
  **/
 guchar *
 gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf)
@@ -640,9 +634,8 @@ gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf)
  * Queries a pointer to the pixel data of a pixbuf.
  *
  * Return value: (array length=length): A pointer to the pixbuf's
- * pixel data.  Please see <xref linkend="image-data"/>
- * for information about how the pixel data is stored in
- * memory.
+ * pixel data.  Please see the section on [image data](image-data)
+ * for information about how the pixel data is stored in memory.
  *
  * Rename to: gdk_pixbuf_get_pixels
  *
@@ -696,8 +689,8 @@ gdk_pixbuf_get_height (const GdkPixbuf *pixbuf)
  * gdk_pixbuf_get_rowstride:
  * @pixbuf: A pixbuf.
  *
- * Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row
- * and the start of the next row.
+ * Queries the rowstride of a pixbuf, which is the number of bytes between
+ * the start of a row and the start of the next row.
  *
  * Return value: Distance between row starts.
  **/
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index 47a50f5..9c992b6 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -621,8 +621,9 @@ save_rle_decoder (GString     *gstring,
  * Generates C source code suitable for compiling images directly 
  * into programs. 
  *
- * gdk-pixbuf ships with a program called <command>gdk-pixbuf-csource</command> 
- * which offers a command line interface to this function.
+ * gdk-pixbuf ships with a program called
+ * [gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command
+ * line interface to this function.
  *
  * Returns: a newly-allocated string containing the C source form
  *   of @pixdata.
@@ -864,28 +865,27 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
  * ship a program with images, but don't want to depend on any
  * external files.
  *
- * gdk-pixbuf ships with a program called <command>gdk-pixbuf-csource</command> 
+ * gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource],
  * which allows for conversion of #GdkPixbufs into such a inline representation.
- * In almost all cases, you should pass the <option>--raw</option> flag to
- * <command>gdk-pixbuf-csource</command>. A sample invocation would be:
+ * In almost all cases, you should pass the `--raw` option to
+ * `gdk-pixbuf-csource`. A sample invocation would be:
  *
- * <informalexample><programlisting>
+ * |[
  *  gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
- * </programlisting></informalexample>
+ * ]|
  * 
  * For the typical case where the inline pixbuf is read-only static data,
  * you don't need to copy the pixel data unless you intend to write to
- * it, so you can pass %FALSE for @copy_pixels.  (If you pass 
- * <option>--rle</option> to <command>gdk-pixbuf-csource</command>, a copy 
- * will be made even if @copy_pixels is %FALSE, so using this option is 
- * generally a bad idea.)
+ * it, so you can pass %FALSE for @copy_pixels.  (If you pass `--rle` to
+ * `gdk-pixbuf-csource`, a copy will be made even if @copy_pixels is %FALSE,
+ * so using this option is generally a bad idea.)
  *
  * If you create a pixbuf from const inline data compiled into your
  * program, it's probably safe to ignore errors and disable length checks, 
  * since things will always succeed:
- * <informalexample><programlisting>
+ * |[
  * pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);
- * </programlisting></informalexample>
+ * ]|
  *
  * For non-const inline data, you could get out of memory. For untrusted 
  * inline data located at runtime, you could have corrupt inline data in
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]