docs: Documentation checking fixes

 • Add some new symbols to sections.txt, and remove old ones
 • Add some missing API version indexes to the documentation
 • Add a few missing documentation comments
 • Update the list of ignored files to include new headers which are not
   public API

https://bugzilla.gnome.org/show_bug.cgi?id=774446

8 files changed, 120 insertions, 25 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index d03831c29..334cccc26 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -103,7 +103,19 @@ IGNORE_HFILES = \
 	totem-search-entry.h		\
 	gd-tagged-entry.h		\
 	gd-fullscreen-filter.h		\
-	screenshot-filename-builder.h
+	screenshot-filename-builder.h	\
+	clock.h				\
+	bacon-video-spinner-actor.h	\
+	bacon-video-controls-actor.h	\
+	totem-time-label.h		\
+	totem-selection-toolbar.h	\
+	totem-main-toolbar.h		\
+	totem-grilo.h			\
+	icon-helpers.h			\
+	bacon-time-label.h		\
+	totem-gst-pixbuf-helpers.h	\
+	totem-time-helpers.h		\
+	$(NULL)
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
diff --git a/docs/reference/totem-docs.xml b/docs/reference/totem-docs.xml
index dba78fd33..941755a32 100644
--- a/docs/reference/totem-docs.xml
+++ b/docs/reference/totem-docs.xml
@@ -46,6 +46,18 @@
 		<title>Index of new symbols in 3.1.5</title>
 		<xi:include href="xml/api-index-3.1.5.xml"><xi:fallback/></xi:include>
 	</index>
+	<index role="3.10">
+		<title>Index of new symbols in 3.10</title>
+		<xi:include href="xml/api-index-3.10.xml"><xi:fallback/></xi:include>
+	</index>
+	<index role="3.12">
+		<title>Index of new symbols in 3.12</title>
+		<xi:include href="xml/api-index-3.12.xml"><xi:fallback/></xi:include>
+	</index>
+	<index role="3.20">
+		<title>Index of new symbols in 3.20</title>
+		<xi:include href="xml/api-index-3.20.xml"><xi:fallback/></xi:include>
+	</index>
 	<index id="api-index-deprecated" role="deprecated">
 		<title>Index of deprecated symbols</title>
 		<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
diff --git a/docs/reference/totem-sections.txt b/docs/reference/totem-sections.txt
index 53e8ed9ed..4e69c9f3d 100644
--- a/docs/reference/totem-sections.txt
+++ b/docs/reference/totem-sections.txt
@@ -6,51 +6,44 @@ TotemObject
 TotemRemoteCommand
 TotemRemoteSetting
 TOTEM_GSETTINGS_SCHEMA
-totem_object_plugins_init
-totem_object_plugins_shutdown
 totem_object_show_error
 totem_object_exit
-totem_object_add_to_playlist_and_play
 totem_object_play
 totem_object_play_pause
-totem_pause
 totem_object_stop
-totem_object_set_fullscreen
-totem_object_fullscreen_toggle
 totem_object_seek_next
 totem_object_seek_previous
-totem_next_angle
 totem_object_remote_get_setting
 totem_object_remote_set_setting
 totem_object_seek_time
 totem_object_seek_relative
 totem_object_set_volume
-totem_object_set_volume_relative
-totem_object_set_volume_toggle_mute
-totem_object_toggle_aspect_ratio
-totem_object_get_aspect_ratio
-totem_object_set_aspect_ratio
-totem_object_set_playlist_index
 totem_object_remote_command
-totem_is_fullscreen
 totem_object_is_playing
 totem_object_is_paused
 totem_object_is_seekable
 totem_object_get_main_window
 totem_object_get_current_mrl
 totem_object_get_video_widget
-totem_get_current_time
 totem_object_set_current_subtitle
 totem_object_get_playlist_length
 totem_object_get_playlist_pos
 totem_object_get_title_at_playlist_pos
-totem_get_short_title
 totem_object_get_volume
-totem_object_get_version
 totem_object_get_supported_content_types
 totem_object_get_supported_uri_schemes
 totem_object_get_rate
 totem_object_set_rate
+totem_object_add_to_playlist
+totem_object_add_to_view
+totem_object_clear_playlist
+totem_object_empty_menu_section
+totem_object_get_current_time
+totem_object_get_menu_section
+totem_object_get_short_title
+totem_object_is_fullscreen
+totem_object_next_angle
+totem_object_pause
 <SUBSECTION Standard>
 TOTEM_OBJECT
 TOTEM_IS_OBJECT
@@ -73,7 +66,6 @@ totem_object_set_mrl_and_play
 totem_object_set_mrl_with_warning
 totem_show_error
 totem_exit
-totem_object_fullscreen_toggle
 totem_next
 totem_play
 totem_play_pause
@@ -84,7 +76,6 @@ totem_remote_set_setting
 totem_seek_time
 totem_stop
 totem_set_volume
-totem_add_to_playlist_and_play
 totem_get_current_mrl
 totem_get_main_window
 totem_get_playlist_length
@@ -97,6 +88,9 @@ totem_is_paused
 totem_is_playing
 totem_is_seekable
 totem_set_current_subtitle
+totem_gst_playbin_get_frame
+totem_gst_tag_list_get_cover
+totem_interface_create_header_button
 </SECTION>
 
 <SECTION>
@@ -169,8 +163,6 @@ bacon_video_widget_get_position
 bacon_video_widget_set_referrer
 bacon_video_widget_get_rotation
 bacon_video_widget_set_rotation
-bacon_video_widget_get_show_cursor
-bacon_video_widget_set_show_cursor
 bacon_video_widget_get_stream_length
 bacon_video_widget_get_subtitles
 bacon_video_widget_get_subtitle
@@ -194,6 +186,14 @@ bacon_video_widget_is_seekable
 bacon_video_widget_get_rate
 bacon_video_widget_set_rate
 bacon_video_widget_step
+bacon_video_widget_get_controls_object
+bacon_video_widget_get_header_controls_object
+bacon_video_widget_set_fullscreen
+bacon_video_widget_set_next_language
+bacon_video_widget_set_next_subtitle
+bacon_video_widget_show_popup
+bacon_video_widget_mark_popup_busy
+bacon_video_widget_unmark_popup_busy
 <SUBSECTION Standard>
 BVW_TYPE_ASPECT_RATIO
 BVW_TYPE_AUDIO_OUTPUT_TYPE
diff --git a/src/backend/bacon-video-widget.c b/src/backend/bacon-video-widget.c
index 44135718d..46edbcfd4 100644
--- a/src/backend/bacon-video-widget.c
+++ b/src/backend/bacon-video-widget.c
@@ -3206,6 +3206,15 @@ bacon_video_widget_set_subtitle (BaconVideoWidget * bvw, int subtitle)
   }
 }
 
+/**
+ * bacon_video_widget_set_next_subtitle:
+ * @bvw: a #BaconVideoWidget
+ *
+ * Switch to the next text subtitle index for the current video. See
+ * bacon_video_widget_set_subtitle().
+ *
+ * Since: 3.12
+ */
 void
 bacon_video_widget_set_next_subtitle (BaconVideoWidget *bvw)
 {
@@ -3494,6 +3503,15 @@ bacon_video_widget_set_language (BaconVideoWidget * bvw, int language)
   g_signal_emit (bvw, bvw_signals[SIGNAL_CHANNELS_CHANGE], 0);
 }
 
+/**
+ * bacon_video_widget_set_next_language:
+ * @bvw: a #BaconVideoWidget
+ *
+ * Switch to the next audio language index for the current video. See
+ * bacon_video_widget_set_language().
+ *
+ * Since: 3.12
+ */
 void
 bacon_video_widget_set_next_language (BaconVideoWidget *bvw)
 {
@@ -3693,6 +3711,15 @@ bacon_video_widget_set_audio_output_type (BaconVideoWidget *bvw,
   set_audio_filter (bvw);
 }
 
+/**
+ * bacon_video_widget_show_popup:
+ * @bvw: a #BaconVideoWidget
+ *
+ * Show the video controls popup, and schedule for it to be hidden again after
+ * a timeout.
+ *
+ * Since: 3.12
+ */
 void
 bacon_video_widget_show_popup (BaconVideoWidget *bvw)
 {
@@ -3702,6 +3729,16 @@ bacon_video_widget_show_popup (BaconVideoWidget *bvw)
   schedule_hiding_popup (bvw);
 }
 
+/**
+ * bacon_video_widget_mark_popup_busy:
+ * @bvw: a #BaconVideoWidget
+ * @reason: human-readable reason for the controls popup being marked as busy
+ *
+ * Mark the video controls popup as busy, for the given @reason. Use
+ * bacon_video_widget_unmark_popup_busy() to undo.
+ *
+ * Since: 3.12
+ */
 void
 bacon_video_widget_mark_popup_busy (BaconVideoWidget *bvw,
 				    const char       *reason)
@@ -3719,6 +3756,17 @@ bacon_video_widget_mark_popup_busy (BaconVideoWidget *bvw,
   unschedule_hiding_popup (bvw);
 }
 
+/**
+ * bacon_video_widget_unmark_popup_busy:
+ * @bvw: a #BaconVideoWidget
+ * @reason: human-readable reason for the controls popup being unmarked as busy
+ *
+ * Unmark the video controls popup as busy, for the given @reason. The popup
+ * must previously have been marked as busy using
+ * bacon_video_widget_mark_popup_busy().
+ *
+ * Since: 3.12
+ */
 void
 bacon_video_widget_unmark_popup_busy (BaconVideoWidget *bvw,
 				      const char       *reason)
@@ -3736,6 +3784,15 @@ bacon_video_widget_unmark_popup_busy (BaconVideoWidget *bvw,
   }
 }
 
+/**
+ * bacon_video_widget_get_controls_object:
+ * @bvw: a #BaconVideoWidget
+ *
+ * Get the widget which displays the video controls.
+ *
+ * Returns: (transfer none): controls widget
+ * Since: 3.12
+ */
 GObject *
 bacon_video_widget_get_controls_object (BaconVideoWidget *bvw)
 {
@@ -3744,6 +3801,15 @@ bacon_video_widget_get_controls_object (BaconVideoWidget *bvw)
   return G_OBJECT (bvw->priv->controls);
 }
 
+/**
+ * bacon_video_widget_get_header_controls_object:
+ * @bvw: a #BaconVideoWidget
+ *
+ * Get the widget which displays the video header controls.
+ *
+ * Returns: (transfer none): header controls widget
+ * Since: 3.20
+ */
 GObject *
 bacon_video_widget_get_header_controls_object (BaconVideoWidget *bvw)
 {
diff --git a/src/totem-interface.c b/src/totem-interface.c
index c9537c264..9fa061046 100644
--- a/src/totem-interface.c
+++ b/src/totem-interface.c
@@ -294,6 +294,9 @@ totem_interface_get_full_path (const char *name)
  * @icon_name: The icon name for the button image
  * @pack_type: A #GtkPackType to tell us where to include the button
  *
+ * Put the given @icon_name into @button, and pack @button into @header
+ * according to @pack_type.
+ *
  * Return value: (transfer none): the button passed as input
  */
 GtkWidget *
diff --git a/src/totem-main-toolbar.c b/src/totem-main-toolbar.c
index 7f16a987b..bbf8e2312 100644
--- a/src/totem-main-toolbar.c
+++ b/src/totem-main-toolbar.c
@@ -32,7 +32,7 @@
 #include "totem-main-toolbar.h"
 #include "griloresources.h"
 
-/**
+/*
  * SECTION:totemmaintoolbar
  * @Short_description: An toolbar with oft-used buttons.
  * @Title: TotemMainToolbar
diff --git a/src/totem-object.c b/src/totem-object.c
index f16cd71ee..a9da66379 100644
--- a/src/totem-object.c
+++ b/src/totem-object.c
@@ -622,7 +622,9 @@ totem_object_get_main_window (TotemObject *totem)
  * @totem: a #TotemObject
  * @id: the ID for the menu section to look up
  *
- * Return value: (transfer none): a #GMenu or %NULL on failure
+ * Get the #GMenu of the given @id from the main Totem #GtkBuilder file.
+ *
+ * Return value: (transfer none) (nullable): a #GMenu or %NULL on failure
  **/
 GMenu *
 totem_object_get_menu_section (TotemObject *totem,
diff --git a/src/totem-selection-toolbar.c b/src/totem-selection-toolbar.c
index e96c1f438..453e93ad2 100644
--- a/src/totem-selection-toolbar.c
+++ b/src/totem-selection-toolbar.c
@@ -32,7 +32,7 @@
 #include "totem-selection-toolbar.h"
 #include "griloresources.h"
 
-/**
+/*
  * SECTION:totemselectiontoolbar
  * @Short_description: An toolbar with oft-used buttons.
  * @Title: TotemSelectionToolbar