clapper: Various documentation cleanups and fixes

src/lib/clapper/clapper-audio-stream.c

@@ -257,9 +257,12 @@ clapper_audio_stream_get_lang_code (ClapperAudioStream *self)
  * clapper_audio_stream_get_lang_name:
  * @stream: a #ClapperAudioStream
  *
- * Get an ISO-639 language code of the @stream.
+ * Get language name of the @stream.
  *
- * Returns: (transfer full) (nullable): the language code of audio stream.
+ * This function will try to return a translated string into current
+ * locale if possible, with a fallback to a name extracted from tags.
+ *
+ * Returns: (transfer full) (nullable): the language name of audio stream.
  */
 gchar *
 clapper_audio_stream_get_lang_name (ClapperAudioStream *self)
@@ -419,7 +422,7 @@ clapper_audio_stream_class_init (ClapperAudioStreamClass *klass)
   /**
    * ClapperAudioStream:lang-name:
    *
-   * Stream full language name determined from lang code.
+   * Stream language name.
    */
   param_specs[PROP_LANG_NAME] = g_param_spec_string ("lang-name",
       NULL, NULL, NULL,

src/lib/clapper/clapper-feature.h

@@ -184,7 +184,7 @@ struct _ClapperFeatureClass
   void (* queue_item_removed) (ClapperFeature *feature, ClapperMediaItem *item, guint index);
 
   /**
-   * ClapperFeatureClass::queue_item_reposition:
+   * ClapperFeatureClass::queue_item_repositioned:
    * @feature: a #ClapperFeature
    * @before: position from which #ClapperMediaItem was removed
    * @after: position at which #ClapperMediaItem was inserted after removal

src/lib/clapper/clapper-marker.c

@@ -156,7 +156,7 @@ clapper_marker_get_marker_type (ClapperMarker *self)
  *
  * Get the title of @marker.
  *
- * Returns: the marker title.
+ * Returns: (nullable): the marker title.
  */
 const gchar *
 clapper_marker_get_title (ClapperMarker *self)

src/lib/clapper/clapper-media-item.c

@@ -176,11 +176,11 @@ clapper_media_item_get_uri (ClapperMediaItem *self)
 /**
  * clapper_media_item_set_suburi:
  * @item: a #ClapperMediaItem
+ * @suburi: an additional URI
  *
  * Set the additional URI of #ClapperMediaItem.
  *
- * This is typically used to add an external subtitles URI
- * to the @item.
+ * This is typically used to add an external subtitles URI to the @item.
  */
 void
 clapper_media_item_set_suburi (ClapperMediaItem *self, const gchar *suburi)
@@ -629,7 +629,7 @@ clapper_media_item_class_init (ClapperMediaItemClass *klass)
       G_PARAM_READABLE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
   /**
-   * ClapperPlayer:timeline:
+   * ClapperMediaItem:timeline:
    *
    * Media timeline.
    */

src/lib/clapper/clapper-player.c

@@ -1158,6 +1158,8 @@ clapper_player_set_volume (ClapperPlayer *self, gdouble volume)
  * @player: a #ClapperPlayer
  *
  * Get the volume of the player.
+ *
+ * Returns: current volume level.
  */
 gdouble
 clapper_player_get_volume (ClapperPlayer *self)
@@ -1649,7 +1651,7 @@ clapper_player_get_subtitle_font_desc (ClapperPlayer *self)
  * Either start or resume the playback of current media item.
  *
  * This function will queue a request for the underlaying #GStreamer
- * pipeline to go into PLAYING state.
+ * pipeline to go into `PLAYING` state.
  */
 void
 clapper_player_play (ClapperPlayer *self)
@@ -1666,8 +1668,8 @@ clapper_player_play (ClapperPlayer *self)
  * Pause the playback of current media item.
  *
  * This function will queue a request for the underlaying #GStreamer
- * pipeline to go into PAUSED state, thus can also be used on a not
- * yet started video to go into PAUSED state first.
+ * pipeline to go into `PAUSED` state, thus can also be used on a not
+ * yet started video to go into `PAUSED` state first.
  */
 void
 clapper_player_pause (ClapperPlayer *self)
@@ -1684,7 +1686,7 @@ clapper_player_pause (ClapperPlayer *self)
  * Stop the playback of current media item.
  *
  * This function will queue a request for the underlaying #GStreamer
- * pipeline to go into READY state.
+ * pipeline to go into `READY` state.
  */
 void
 clapper_player_stop (ClapperPlayer *self)
@@ -1742,9 +1744,6 @@ clapper_player_seek_custom (ClapperPlayer *self, gdouble position, ClapperPlayer
  * @feature: a #ClapperFeature
  *
  * Add another #ClapperFeature to the player.
- *
- * If feature is already added, this function will do nothing,
- * so it is safe to call multiple times if unsure.
  */
 void
 clapper_player_add_feature (ClapperPlayer *self, ClapperFeature *feature)

src/lib/clapper/clapper-queue.c

@@ -749,7 +749,7 @@ clapper_queue_select_index (ClapperQueue *self, guint index)
  * Selects next #ClapperMediaItem from @queue for playback.
  *
  * Note that this will try to select next item in the order
- * of the queue, regardless of #ClapperQueueProgressionMode set.
+ * of the queue, regardless of [enum@Clapper.QueueProgressionMode] set.
  *
  * Returns: %TRUE if there was another media item in queue, %FALSE otherwise.
  */
@@ -780,7 +780,7 @@ clapper_queue_select_next_item (ClapperQueue *self)
  * Selects previous #ClapperMediaItem from @queue for playback.
  *
  * Note that this will try to select previous item in the order
- * of the queue, regardless of #ClapperQueueProgressionMode set.
+ * of the queue, regardless of [enum@Clapper.QueueProgressionMode] set.
  *
  * Returns: %TRUE if there was previous media item in queue, %FALSE otherwise.
  */
@@ -933,7 +933,7 @@ clapper_queue_find_item (ClapperQueue *self, ClapperMediaItem *item, guint *inde
  *
  * Get the number of items in #ClapperQueue.
  *
- * This behaves the same as g_list_model_get_n_items(), and is here
+ * This behaves the same as [method@Gio.ListModel.get_n_items], and is here
  * for code uniformity and convenience to avoid type casting by user.
  *
  * This function is not available in bindings as they already

src/lib/clapper/clapper-stream-list.c

@@ -320,7 +320,7 @@ clapper_stream_list_get_current_index (ClapperStreamList *self)
  *
  * Get the number of streams in #ClapperStreamList.
  *
- * This behaves the same as g_list_model_get_n_items(), and is here
+ * This behaves the same as [method@Gio.ListModel.get_n_items], and is here
  * for code uniformity and convenience to avoid type casting by user.
  *
  * Returns: The number of streams in #ClapperStreamList.

src/lib/clapper/clapper-subtitle-stream.c

@@ -106,9 +106,12 @@ clapper_subtitle_stream_get_lang_code (ClapperSubtitleStream *self)
  * clapper_subtitle_stream_get_lang_name:
  * @stream: a #ClapperSubtitleStream
  *
- * Get an ISO-639 language code of the @stream.
+ * Get language name of the @stream.
  *
- * Returns: (transfer full) (nullable): the language code of subtitle stream.
+ * This function will try to return a translated string into current
+ * locale if possible, with a fallback to a name extracted from tags.
+ *
+ * Returns: (transfer full) (nullable): the language name of subtitle stream.
  */
 gchar *
 clapper_subtitle_stream_get_lang_name (ClapperSubtitleStream *self)
@@ -204,7 +207,7 @@ clapper_subtitle_stream_class_init (ClapperSubtitleStreamClass *klass)
   /**
    * ClapperSubtitleStream:lang-name:
    *
-   * Stream full language name determined from lang code.
+   * Stream language name.
    */
   param_specs[PROP_LANG_NAME] = g_param_spec_string ("lang-name",
       NULL, NULL, NULL,

src/lib/clapper/features/mpris/clapper-mpris.c

@@ -1342,7 +1342,7 @@ clapper_mpris_property_changed (ClapperFeature *feature, GParamSpec *pspec)
  * clapper_mpris_new:
  * @own_name: an unique DBus name with "org.mpris.MediaPlayer2." prefix
  * @identity: a media player friendly name
- * @desktop_entry: (nullable): desktop entry filename
+ * @desktop_entry: (nullable): desktop file basename (without ".desktop" extension)
  *
  * Creates a new #ClapperMpris instance.
  *

src/lib/clapper/features/server/clapper-server.c

@@ -920,7 +920,10 @@ clapper_server_set_port (ClapperServer *self, guint port)
  *
  * Get requested server listening port.
  *
- * Returns: Requested listening port or 0 using random port.
+ * If you want to know the port server is currently listening on,
+ * use [method@Clapper.Server.get_current_port] instead.
+ *
+ * Returns: Requested listening port or 0 when using random port.
  */
 guint
 clapper_server_get_port (ClapperServer *self)
@@ -965,9 +968,8 @@ clapper_server_get_current_port (ClapperServer *self)
  *
  * Set whether remote @server clients can control [class@Clapper.Queue].
  *
- * This includes ability to add/remove items from
- * the queue and selecting current item for playback
- * remotely using WebSocket messages.
+ * This includes ability to add/remove items from the queue and selecting
+ * current item for playback remotely using WebSocket messages.
  *
  * You probably want to keep this disabled if your application
  * is supposed to manage what is played now and not WebSocket client.