GNOME.org
 

[totem] docs: Fix various minor problems with the API documentation

commit 3effa6dd566572882a8cc29755f7e4ee2424efd8
Author: Philip Withnall <philip tecnocode co uk>
Date:   Tue Jul 5 20:26:08 2011 +0100

    docs: Fix various minor problems with the API documentation
    
    Mostly fixes for my incorrect usage of the const syntax (â%â) to denote
    numeric constants, which it turns out should be denoted using
    <code class="literal">0</code> instead (for example).

 src/backend/bacon-video-widget-gst-0.10.c   |   61 +++++++++++++--------------
 src/egg-macros.h                            |    2 +-
 src/plugins/chapters/totem-chapters-utils.c |    4 +-
 src/plugins/chapters/totem-cmml-parser.c    |    4 +-
 src/plugins/chapters/totem-edit-chapter.c   |    4 +-
 src/totem-object.c                          |   18 ++++----
 6 files changed, 46 insertions(+), 47 deletions(-)
---
diff --git a/src/backend/bacon-video-widget-gst-0.10.c b/src/backend/bacon-video-widget-gst-0.10.c
index 298e93d..df1c83f 100644
--- a/src/backend/bacon-video-widget-gst-0.10.c
+++ b/src/backend/bacon-video-widget-gst-0.10.c
@@ -779,7 +779,7 @@ bacon_video_widget_class_init (BaconVideoWidgetClass * klass)
   /**
    * BaconVideoWidget:position:
    *
-   * The current position in the stream, as a percentage between %0 and %1.
+   * The current position in the stream, as a percentage between <code class="literal">0</code> and <code class="literal">1</code>.
    **/
   g_object_class_install_property (object_class, PROP_POSITION,
                                    g_param_spec_double ("position", NULL, NULL,
@@ -823,7 +823,7 @@ bacon_video_widget_class_init (BaconVideoWidgetClass * klass)
   /**
    * BaconVideoWidget:volume:
    *
-   * The current volume level, as a percentage between %0 and %1.
+   * The current volume level, as a percentage between <code class="literal">0</code> and <code class="literal">1</code>.
    **/
   g_object_class_install_property (object_class, PROP_VOLUME,
 	                           g_param_spec_double ("volume", NULL, NULL,
@@ -1069,7 +1069,7 @@ bacon_video_widget_class_init (BaconVideoWidgetClass * klass)
    * BaconVideoWidget::tick:
    * @current_time: the current position in the stream, in milliseconds since the beginning of the stream
    * @stream_length: the length of the stream, in milliseconds
-   * @current_position: the current position in the stream, as a percentage between %0 and %1
+   * @current_position: the current position in the stream, as a percentage between <code class="literal">0</code> and <code class="literal">1</code>
    * @seekable: %TRUE if the stream can be seeked, %FALSE otherwise
    *
    * Emitted every time an important time event happens, or at regular intervals when playing a stream.
@@ -1086,7 +1086,7 @@ bacon_video_widget_class_init (BaconVideoWidgetClass * klass)
 
   /**
    * BaconVideoWidget::buffering:
-   * @percentage: the percentage of buffering completed, between %0 and %1
+   * @percentage: the percentage of buffering completed, between <code class="literal">0</code> and <code class="literal">1</code>
    *
    * Emitted regularly when a network stream is being buffered, to provide status updates on the buffering
    * progress.
@@ -1123,7 +1123,7 @@ bacon_video_widget_class_init (BaconVideoWidgetClass * klass)
 
   /**
    * BaconVideoWidget::download-buffering:
-   * @percentage: the percentage of download buffering completed, between %0 and %1
+   * @percentage: the percentage of download buffering completed, between <code class="literal">0</code> and <code class="literal">1</code>
    *
    * Emitted regularly when a network stream is being cached on disk, to provide status
    *  updates on the buffering level of the stream.
@@ -2708,8 +2708,8 @@ bacon_video_widget_get_backend_name (BaconVideoWidget * bvw)
  *
  * Returns the index of the current subtitles.
  *
- * If the widget is not playing, %-2 will be returned. If no subtitles are
- * being used, %-1 is returned.
+ * If the widget is not playing, <code class="literal">-2</code> will be returned. If no subtitles are
+ * being used, <code class="literal">-1</code> is returned.
  *
  * Return value: the subtitle index
  **/
@@ -2738,7 +2738,7 @@ bacon_video_widget_get_subtitle (BaconVideoWidget * bvw)
  * @bvw: a #BaconVideoWidget
  * @subtitle: a subtitle index
  *
- * Sets the subtitle index for @bvw. If @subtitle is %-1, no subtitles will
+ * Sets the subtitle index for @bvw. If @subtitle is <code class="literal">-1</code>, no subtitles will
  * be used.
  **/
 void
@@ -2940,7 +2940,7 @@ bacon_video_widget_get_languages (BaconVideoWidget * bvw)
  *
  * Returns the index of the current audio language.
  *
- * If the widget is not playing, or the default language is in use, %-1 will be returned.
+ * If the widget is not playing, or the default language is in use, <code class="literal">-1</code> will be returned.
  *
  * Return value: the audio language index
  **/
@@ -2963,7 +2963,7 @@ bacon_video_widget_get_language (BaconVideoWidget * bvw)
  * @bvw: a #BaconVideoWidget
  * @language: an audio language index
  *
- * Sets the audio language index for @bvw. If @language is %-1, the default language will
+ * Sets the audio language index for @bvw. If @language is <code class="literal">-1</code>, the default language will
  * be used.
  **/
 void
@@ -3013,8 +3013,8 @@ connection_speed_enum_to_kbps (gint speed)
  * bacon_video_widget_get_connection_speed:
  * @bvw: a #BaconVideoWidget
  *
- * Returns the current connection speed, where %0 is the lowest speed
- * and %11 is the highest.
+ * Returns the current connection speed, where <code class="literal">0</code> is the lowest speed
+ * and <code class="literal">11</code> is the highest.
  *
  * Return value: the connection speed index
  **/
@@ -3032,8 +3032,8 @@ bacon_video_widget_get_connection_speed (BaconVideoWidget * bvw)
  * @bvw: a #BaconVideoWidget
  * @speed: the connection speed index
  *
- * Sets the connection speed from the given @speed index, where %0 is the lowest speed
- * and %11 is the highest.
+ * Sets the connection speed from the given @speed index, where <code class="literal">0</code> is the lowest speed
+ * and <code class="literal">11</code> is the highest.
  **/
 void
 bacon_video_widget_set_connection_speed (BaconVideoWidget * bvw, int speed)
@@ -3202,9 +3202,9 @@ set_audio_filter (BaconVideoWidget *bvw)
  * @bvw: a #BaconVideoWidget
  *
  * Returns the current audio output type (e.g. how many speaker channels)
- * from #BaconVideoWidgetAudioOutputType.
+ * from #BvwAudioOutputType.
  *
- * Return value: the audio output type, or %-1
+ * Return value: the audio output type, or <code class="literal">-1</code>
  **/
 BvwAudioOutputType
 bacon_video_widget_get_audio_output_type (BaconVideoWidget *bvw)
@@ -4251,9 +4251,9 @@ bacon_video_widget_can_set_volume (BaconVideoWidget * bvw)
 /**
  * bacon_video_widget_set_volume:
  * @bvw: a #BaconVideoWidget
- * @volume: the new volume level, as a percentage between %0 and %1
+ * @volume: the new volume level, as a percentage between <code class="literal">0</code> and <code class="literal">1</code>
  *
- * Sets the volume level of the stream as a percentage between %0 and %1.
+ * Sets the volume level of the stream as a percentage between <code class="literal">0</code> and <code class="literal">1</code>.
  *
  * If bacon_video_widget_can_set_volume() returns %FALSE, this is a no-op.
  **/
@@ -4278,9 +4278,9 @@ bacon_video_widget_set_volume (BaconVideoWidget * bvw, double volume)
  * bacon_video_widget_get_volume:
  * @bvw: a #BaconVideoWidget
  *
- * Returns the current volume level, as a percentage between %0 and %1.
+ * Returns the current volume level, as a percentage between <code class="literal">0</code> and <code class="literal">1</code>.
  *
- * Return value: the volume as a percentage between %0 and %1
+ * Return value: the volume as a percentage between <code class="literal">0</code> and <code class="literal">1</code>
  **/
 double
 bacon_video_widget_get_volume (BaconVideoWidget * bvw)
@@ -4741,7 +4741,7 @@ bacon_video_widget_set_auto_resize (BaconVideoWidget * bvw,
  * @bvw: a #BaconVideoWidget
  * @ratio: the new aspect ratio
  *
- * Sets the aspect ratio used by the widget, from #BaconVideoWidgetAspectRatio.
+ * Sets the aspect ratio used by the widget, from #BvwAspectRatio.
  *
  * Changes to this take effect immediately.
  **/
@@ -4761,7 +4761,7 @@ bacon_video_widget_set_aspect_ratio (BaconVideoWidget *bvw,
  * @bvw: a #BaconVideoWidget
  *
  * Returns the current aspect ratio used by the widget, from
- * #BaconVideoWidgetAspectRatio.
+ * #BvwAspectRatio.
  *
  * Return value: the aspect ratio
  **/
@@ -4780,7 +4780,7 @@ bacon_video_widget_get_aspect_ratio (BaconVideoWidget *bvw)
  * @ratio: the new scale ratio
  *
  * Sets the ratio by which the widget will scale videos when they are
- * displayed. If @ratio is set to %0, the highest ratio possible will
+ * displayed. If @ratio is set to <code class="literal">0</code>, the highest ratio possible will
  * be chosen.
  **/
 void
@@ -5121,9 +5121,9 @@ bacon_video_widget_set_video_property (BaconVideoWidget *bvw,
  * @bvw: a #BaconVideoWidget
  *
  * Returns the current position in the stream, as a value between
- * %0 and %1.
+ * <code class="literal">0</code> and <code class="literal">1</code>.
  *
- * Return value: the current position, or %-1
+ * Return value: the current position, or <code class="literal">-1</code>
  **/
 double
 bacon_video_widget_get_position (BaconVideoWidget * bvw)
@@ -5140,7 +5140,7 @@ bacon_video_widget_get_position (BaconVideoWidget * bvw)
  * Returns the current position in the stream, as the time (in milliseconds)
  * since the beginning of the stream.
  *
- * Return value: time since the beginning of the stream, in milliseconds, or %-1
+ * Return value: time since the beginning of the stream, in milliseconds, or <code class="literal">-1</code>
  **/
 gint64
 bacon_video_widget_get_current_time (BaconVideoWidget * bvw)
@@ -5156,7 +5156,7 @@ bacon_video_widget_get_current_time (BaconVideoWidget * bvw)
  *
  * Returns the total length of the stream, in milliseconds.
  *
- * Return value: the stream length, in milliseconds, or %-1
+ * Return value: the stream length, in milliseconds, or <code class="literal">-1</code>
  **/
 gint64
 bacon_video_widget_get_stream_length (BaconVideoWidget * bvw)
@@ -5271,7 +5271,7 @@ done:
  *
  * Returns an array of MRLs available for the given @device and media @type.
  *
- * @device should typically be the number of the device (e.g. %0 for the first
+ * @device should typically be the number of the device (e.g. <code class="literal">0</code> for the first
  * DVD drive.
  *
  * @type can be any value from #TotemDiscMediaType, but a %BVW_ERROR_INVALID_LOCATION error
@@ -5877,8 +5877,7 @@ bacon_video_widget_get_current_frame (BaconVideoWidget * bvw)
  * Returns the #GOptionGroup containing command-line options for
  * #BaconVideoWidget.
  *
- * Applications must call either this or bacon_video_widget_init_backend() exactly
- * once; but not both.
+ * Applications must call either this exactly once.
  *
  * Return value: a #GOptionGroup giving command-line options for #BaconVideoWidget
  **/
@@ -5968,7 +5967,7 @@ bvw_set_playback_direction (BaconVideoWidget *bvw, gboolean forward)
  *
  * Creates a new #BaconVideoWidget.
  *
- * @width and @height give the initial or expected video height. Set them to %-1 if the
+ * @width and @height give the initial or expected video height. Set them to <code class="literal">-1</code> if the
  * video size is unknown. For small videos, #BaconVideoWidget will be configured differently.
  *
  * A #BvwError will be returned on error.
diff --git a/src/egg-macros.h b/src/egg-macros.h
index a1dd396..8e9a5a0 100644
--- a/src/egg-macros.h
+++ b/src/egg-macros.h
@@ -1,4 +1,4 @@
-/**
+/*
  * Useful macros.
  *
  * Author:
diff --git a/src/plugins/chapters/totem-chapters-utils.c b/src/plugins/chapters/totem-chapters-utils.c
index c3aa497..dc740e9 100644
--- a/src/plugins/chapters/totem-chapters-utils.c
+++ b/src/plugins/chapters/totem-chapters-utils.c
@@ -22,14 +22,14 @@
  * Totem is covered by.
  */
 
-/**
+/*
  * SECTION:totem-chapters-utils
  * @short_description: misc helper functions
  * @stability: Unstable
  * @include: totem-chapters-utils.h
  *
  * These functions are used for misc operations within chapters plugin.
- **/
+ */
 
 #include <glib.h>
 
diff --git a/src/plugins/chapters/totem-cmml-parser.c b/src/plugins/chapters/totem-cmml-parser.c
index 3b7447f..e0ca7b2 100644
--- a/src/plugins/chapters/totem-cmml-parser.c
+++ b/src/plugins/chapters/totem-cmml-parser.c
@@ -22,13 +22,13 @@
  * Totem is covered by.
  */
 
-/**
+/*
  * SECTION:totem-cmml-parser
  * @short_description: parser for CMML files
  * @stability: Unstable
  *
  * These functions are used to parse CMML files for chapters.
- **/
+ */
 
 #include "config.h"
 
diff --git a/src/plugins/chapters/totem-edit-chapter.c b/src/plugins/chapters/totem-edit-chapter.c
index d836a2a..eb81b28 100644
--- a/src/plugins/chapters/totem-edit-chapter.c
+++ b/src/plugins/chapters/totem-edit-chapter.c
@@ -22,14 +22,14 @@
  * Totem is covered by.
  */
 
-/**
+/*
  * SECTION:totem-edit-chapter
  * @short_description: dialog to add new chapters in chapters plugin
  * @stability: Unstable
  * @include: totem-edit-chapter.h
  *
  * #TotemEditChapter dialog is used for entering names of new chapters in the chapters plugin
- **/
+ */
 
 #include <gtk/gtk.h>
 
diff --git a/src/totem-object.c b/src/totem-object.c
index 32298d2..e7d7d03 100644
--- a/src/totem-object.c
+++ b/src/totem-object.c
@@ -591,10 +591,10 @@ totem_object_get_playlist_length (TotemObject *totem)
  * totem_object_get_playlist_pos:
  * @totem: a #TotemObject
  *
- * Returns the %0-based index of the current entry in the playlist. If
- * there is no current entry in the playlist, %-1 is returned.
+ * Returns the <code class="literal">0</code>-based index of the current entry in the playlist. If
+ * there is no current entry in the playlist, <code class="literal">-1</code> is returned.
  *
- * Return value: the index of the current playlist entry, or %-1
+ * Return value: the index of the current playlist entry, or <code class="literal">-1</code>
  **/
 int
 totem_object_get_playlist_pos (TotemObject *totem)
@@ -605,7 +605,7 @@ totem_object_get_playlist_pos (TotemObject *totem)
 /**
  * totem_object_get_title_at_playlist_pos:
  * @totem: a #TotemObject
- * @playlist_index: the %0-based entry index
+ * @playlist_index: the <code class="literal">0</code>-based entry index
  *
  * Gets the title of the playlist entry at @index.
  *
@@ -2005,7 +2005,7 @@ totem_action_set_zoom (TotemObject *totem,
  * totem_object_get_volume:
  * @totem: a #TotemObject
  *
- * Gets the current volume level, as a value between %0.0 and %1.0.
+ * Gets the current volume level, as a value between <code class="literal">0.0</code> and <code class="literal">1.0</code>.
  *
  * Return value: the volume level
  **/
@@ -2020,7 +2020,7 @@ totem_object_get_volume (TotemObject *totem)
  * @totem: a #TotemObject
  * @volume: the new absolute volume value
  *
- * Sets the volume, with %1.0 being the maximum, and %0.0 being the minimum level.
+ * Sets the volume, with <code class="literal">1.0</code> being the maximum, and <code class="literal">0.0</code> being the minimum level.
  **/
 void
 totem_object_action_volume (TotemObject *totem, double volume)
@@ -2036,8 +2036,8 @@ totem_object_action_volume (TotemObject *totem, double volume)
  * @totem: a #TotemObject
  * @off_pct: the value by which to increase or decrease the volume
  *
- * Sets the volume relative to its current level, with %1.0 being the
- * maximum, and %0.0 being the minimum level.
+ * Sets the volume relative to its current level, with <code class="literal">1.0</code> being the
+ * maximum, and <code class="literal">0.0</code> being the minimum level.
  **/
 void
 totem_action_volume_relative (TotemObject *totem, double off_pct)
@@ -2958,7 +2958,7 @@ totem_action_next_angle (TotemObject *totem)
  * @totem: a #TotemObject
  * @index: the new playlist index
  *
- * Sets the %0-based playlist index to @index, causing Totem to load and
+ * Sets the <code class="literal">0</code>-based playlist index to @index, causing Totem to load and
  * start playing that playlist entry.
  *
  * If @index is higher than the current length of the playlist, this
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]