docs: various doc fixes

No short-desc as we have them in the element details.
Also keep things (Makefile.am and sections.txt) sorted.
Reword ambigous returns. No text after since please.

11 files changed, 148 insertions, 154 deletions

diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index e12a2f138..c5504b19e 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -117,14 +117,18 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/aacparse/gstaacparse.h \
 	$(top_srcdir)/gst/amrparse/gstamrparse.h \
 	$(top_srcdir)/gst/camerabin/gstcamerabin.h \
-	$(top_srcdir)/gst/legacyresample/gstlegacyresample.h \
 	$(top_srcdir)/gst/deinterlace/gstdeinterlace.h \
 	$(top_srcdir)/gst/dccp/gstdccpclientsink.h \
 	$(top_srcdir)/gst/dccp/gstdccpclientsrc.h \
 	$(top_srcdir)/gst/dccp/gstdccpserversink.h \
 	$(top_srcdir)/gst/dccp/gstdccpserversrc.h \
+	$(top_srcdir)/gst/dtmf/gstdtmfsrc.h \
+	$(top_srcdir)/gst/dtmf/gstrtpdtmfsrc.h \
+	$(top_srcdir)/gst/dtmf/gstrtpdtmfdepay.h \
 	$(top_srcdir)/gst/dvdspu/gstdvdspu.h \
 	$(top_srcdir)/gst/festival/gstfestival.h \
+	$(top_srcdir)/gst/legacyresample/gstlegacyresample.h \
+	$(top_srcdir)/gst/liveadder/liveadder.h \
 	$(top_srcdir)/gst/mxf/mxfdemux.h \
 	$(top_srcdir)/gst/nuvdemux/gstnuvdemux.h \
 	$(top_srcdir)/gst/rawparse/gstaudioparse.h \
@@ -148,11 +152,6 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/videosignal/gstvideomark.h \
 	$(top_srcdir)/gst/valve/gstvalve.h \
 	$(top_srcdir)/gst/y4m/gsty4mencode.h \
-	$(top_srcdir)/gst/liveadder/liveadder.h \
-	$(top_srcdir)/gst/dtmf/gstdtmfsrc.h \
-	$(top_srcdir)/gst/dtmf/gstrtpdtmfsrc.h \
-	$(top_srcdir)/gst/dtmf/gstrtpdtmfdepay.h \
-	$(top_srcdir)/gst/dtmf/gstrtpdtmfcommon.h \
 	$(top_srcdir)/sys/dvb/gstdvbsrc.h
 
 # Images to copy into HTML directory.
diff --git a/docs/plugins/gst-plugins-bad-plugins-sections.txt b/docs/plugins/gst-plugins-bad-plugins-sections.txt
index 916c5e597..a2829ef96 100644
--- a/docs/plugins/gst-plugins-bad-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-bad-plugins-sections.txt
@@ -230,6 +230,25 @@ gst_dfbsurface_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-dtmfsrc</FILE>
+<TITLE>dtmfsrc</TITLE>
+GstDTMFSrc
+<SUBSECTION Standard>
+GstDTMFEventType
+GstDTMFSrcEvent
+GstDTMFSrcClass
+GST_TYPE_DTMF_SRC
+GST_DTMF_SRC
+GST_DTMF_SRC_CAST
+GST_DTMF_SRC_CLASS
+GST_DTMF_SRC_GET_CLASS
+GST_IS_DTMF_SRC
+GST_IS_DTMF_SRC_CLASS
+gst_dtmf_src_get_type
+gst_dtmf_src_plugin_init
+</SECTION>
+
+<SECTION>
 <FILE>element-dvbsrc</FILE>
 <TITLE>dvbsrc</TITLE>
 GstDvbSrc
@@ -360,6 +379,38 @@ gst_jack_audio_sink_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-legacyresample</FILE>
+<TITLE>legacyresample</TITLE>
+GstLegacyresample
+<SUBSECTION Standard>
+GstLegacyresampleClass
+GST_LEGACYRESAMPLE
+GST_LEGACYRESAMPLE_CLASS
+GST_IS_LEGACYRESAMPLE
+GST_IS_LEGACYRESAMPLE_CLASS
+GST_TYPE_LEGACYRESAMPLE
+gst_legacyresample_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-liveadder</FILE>
+<TITLE>liveadder</TITLE>
+GstLiveAdder
+<SUBSECTION Standard>
+GstLiveAdderClass
+GST_IS_LIVE_ADDER
+GST_IS_LIVE_ADDER_CLASS
+GST_IS_MXF_DEMUX_PAD
+GST_LIVE_ADDER
+GST_LIVE_ADDER_CLASS
+GST_LIVE_ADDER_GET_CLASS
+GST_TYPE_LIVE_ADDER
+GstLiveAdderFormat
+GstLiveAdderFunction
+gst_live_adder_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gstbasemetadata</FILE>
 <TITLE>GstBaseMetadata</TITLE>
 GstBaseMetadata
@@ -524,6 +575,71 @@ gst_output_selector_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-rtpdtmfdepay</FILE>
+<TITLE>rtpdtmfdepay</TITLE>
+GstRtpDTMFDepay
+<SUBSECTION Standard>
+GstRtpDTMFDepayClass
+GST_TYPE_RTP_DTMF_DEPAY
+GST_IS_RTP_DTMF_DEPAY
+GST_IS_RTP_DTMF_DEPAY_CLASS
+GST_RTP_DTMF_DEPAY
+GST_RTP_DTMF_DEPAY_CLASS
+gst_rtp_dtmf_depay_plugin_init
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpdtmfmux</FILE>
+<TITLE>rtpdtmfmux</TITLE>
+GstRTPDTMFMux
+<SUBSECTION Standard>
+GST_IS_RTP_DTMF_MUX
+GST_IS_RTP_DTMF_MUX_CLASS
+GST_TYPE_RTP_DTMF_MUX
+GstRTPDTMFMuxClass
+GST_RTP_DTMF_MUX
+GST_RTP_DTMF_MUX_CLASS
+gst_rtp_dtmf_mux_get_type
+gst_rtp_dtmf_mux_plugin_init
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpdtmfsrc</FILE>
+<TITLE>rtpdtmfsrc</TITLE>
+GstRTPDTMFSrc
+<SUBSECTION Standard>
+GstRTPDTMFSrcClass
+GST_TYPE_RTP_DTMF_SRC
+GST_IS_RTP_DTMF_SRC
+GST_IS_RTP_DTMF_SRC_CLASS
+GST_RTP_DTMF_SRC
+GST_RTP_DTMF_SRC_CAST
+GST_RTP_DTMF_SRC_CLASS
+GST_RTP_DTMF_SRC_GET_CLASS
+gst_rtp_dtmf_src_get_type
+gst_rtp_dtmf_src_plugin_init
+GstRTPDTMFPayload
+GstRTPDTMFSrcEvent
+GstRTPDTMFEventType
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpmux</FILE>
+<TITLE>rtpmux</TITLE>
+GstRTPMux
+<SUBSECTION Standard>
+GST_IS_RTP_MUX
+GST_IS_RTP_MUX_CLASS
+GST_RTP_MUX
+GST_RTP_MUX_CLASS
+GST_RTP_MUX_GET_CLASS
+GST_TYPE_RTP_MUX
+GstRTPMuxClass
+gst_rtp_mux_plugin_init
+gst_rtp_session_set_ssrc
+</SECTION>
+
+<SECTION>
 <FILE>element-gstrtpbin</FILE>
 <TITLE>gstrtpbin</TITLE>
 GstRtpBin
@@ -708,20 +824,6 @@ gst_stereo_get_type
 </SECTION>
 
 <SECTION>
-<FILE>element-legacyresample</FILE>
-<TITLE>legacyresample</TITLE>
-GstLegacyresample
-<SUBSECTION Standard>
-GstLegacyresampleClass
-GST_LEGACYRESAMPLE
-GST_LEGACYRESAMPLE_CLASS
-GST_IS_LEGACYRESAMPLE
-GST_IS_LEGACYRESAMPLE_CLASS
-GST_TYPE_LEGACYRESAMPLE
-gst_legacyresample_get_type
-</SECTION>
-
-<SECTION>
 <FILE>element-theoradecexp</FILE>
 <TITLE>theoradecexp</TITLE>
 GstTheoraExpDec
@@ -777,6 +879,21 @@ gst_trm_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-valve</FILE>
+<TITLE>valve</TITLE>
+GstValve
+<SUBSECTION Standard>
+GstValveClass
+GstValvePrivate
+gst_valve_get_type
+GST_IS_VALVE
+GST_IS_VALVE_CLASS
+GST_TYPE_VALVE
+GST_VALVE
+GST_VALVE_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>element-videoanalyse</FILE>
 <TITLE>videoanalyse</TITLE>
 GstVideoAnalyse
@@ -874,120 +991,3 @@ GST_TYPE_Y4M_ENCODE
 gst_y4m_encode_get_type
 </SECTION>
 
-
-<SECTION>
-<FILE>element-liveadder</FILE>
-<TITLE>liveadder</TITLE>
-GstLiveAdder
-<SUBSECTION Standard>
-GstLiveAdderClass
-GST_IS_LIVE_ADDER
-GST_IS_LIVE_ADDER_CLASS
-GST_IS_MXF_DEMUX_PAD
-GST_LIVE_ADDER
-GST_LIVE_ADDER_CLASS
-GST_LIVE_ADDER_GET_CLASS
-GST_TYPE_LIVE_ADDER
-GstLiveAdderFormat
-GstLiveAdderFunction
-gst_live_adder_get_type
-</SECTION>
-
-<SECTION>
-<FILE>element-valve</FILE>
-<TITLE>valve</TITLE>
-GstValve
-<SUBSECTION Standard>
-GstValveClass
-GstValvePrivate
-gst_valve_get_type
-GST_IS_VALVE
-GST_IS_VALVE_CLASS
-GST_TYPE_VALVE
-GST_VALVE
-GST_VALVE_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>element-dtmfsrc</FILE>
-<TITLE>dtmfsrc</TITLE>
-GstDTMFSrc
-<SUBSECTION Standard>
-GstDTMFEventType
-GstDTMFSrcEvent
-GstDTMFSrcClass
-GST_TYPE_DTMF_SRC
-GST_DTMF_SRC
-GST_DTMF_SRC_CAST
-GST_DTMF_SRC_CLASS
-GST_DTMF_SRC_GET_CLASS
-GST_IS_DTMF_SRC
-GST_IS_DTMF_SRC_CLASS
-gst_dtmf_src_get_type
-gst_dtmf_src_plugin_init
-</SECTION>
-
-<SECTION>
-<FILE>element-rtpdtmfsrc</FILE>
-<TITLE>rtpdtmfsrc</TITLE>
-GstRTPDTMFSrc
-<SUBSECTION Standard>
-GstRTPDTMFSrcClass
-GST_TYPE_RTP_DTMF_SRC
-GST_IS_RTP_DTMF_SRC
-GST_IS_RTP_DTMF_SRC_CLASS
-GST_RTP_DTMF_SRC
-GST_RTP_DTMF_SRC_CAST
-GST_RTP_DTMF_SRC_CLASS
-GST_RTP_DTMF_SRC_GET_CLASS
-gst_rtp_dtmf_src_get_type
-gst_rtp_dtmf_src_plugin_init
-GstRTPDTMFPayload
-GstRTPDTMFSrcEvent
-GstRTPDTMFEventType
-</SECTION>
-
-<SECTION>
-<FILE>element-rtpdtmfdepay</FILE>
-<TITLE>rtpdtmfdepay</TITLE>
-GstRtpDTMFDepay
-<SUBSECTION Standard>
-GstRtpDTMFDepayClass
-GST_TYPE_RTP_DTMF_DEPAY
-GST_IS_RTP_DTMF_DEPAY
-GST_IS_RTP_DTMF_DEPAY_CLASS
-GST_RTP_DTMF_DEPAY
-GST_RTP_DTMF_DEPAY_CLASS
-gst_rtp_dtmf_depay_plugin_init
-</SECTION>
-
-<SECTION>
-<FILE>element-rtpmux</FILE>
-<TITLE>rtpmux</TITLE>
-GstRTPMux
-<SUBSECTION Standard>
-GST_IS_RTP_MUX
-GST_IS_RTP_MUX_CLASS
-GST_RTP_MUX
-GST_RTP_MUX_CLASS
-GST_RTP_MUX_GET_CLASS
-GST_TYPE_RTP_MUX
-GstRTPMuxClass
-gst_rtp_mux_plugin_init
-gst_rtp_session_set_ssrc
-</SECTION>
-
-<SECTION>
-<FILE>element-rtpdtmfmux</FILE>
-<TITLE>rtpdtmfmux</TITLE>
-GstRTPDTMFMux
-<SUBSECTION Standard>
-GST_IS_RTP_DTMF_MUX
-GST_IS_RTP_DTMF_MUX_CLASS
-GST_TYPE_RTP_DTMF_MUX
-GstRTPDTMFMuxClass
-GST_RTP_DTMF_MUX
-GST_RTP_DTMF_MUX_CLASS
-gst_rtp_dtmf_mux_get_type
-gst_rtp_dtmf_mux_plugin_init
-</SECTION>
diff --git a/gst/camerabin/gstcamerabin.c b/gst/camerabin/gstcamerabin.c
index d3965bfc2..5dbd386fd 100644
--- a/gst/camerabin/gstcamerabin.c
+++ b/gst/camerabin/gstcamerabin.c
@@ -20,7 +20,6 @@
 
 /**
  * SECTION:element-camerabin
- * @short_description: camera capture bin
  *
  * GstCameraBin is a high-level camera object that encapsulates the gstreamer
  * internals and provides a task based API for the application. It consists of
diff --git a/gst/dtmf/gstdtmfsrc.c b/gst/dtmf/gstdtmfsrc.c
index 8c5485b17..8595adf8a 100644
--- a/gst/dtmf/gstdtmfsrc.c
+++ b/gst/dtmf/gstdtmfsrc.c
@@ -27,7 +27,6 @@
 
 /**
  * SECTION:element-dtmfsrc
- * @short_description: Generates DTMF packets
  * @see_also: rtpdtmsrc, rtpdtmfmuxx
  *
  * The DTMFSrc element generates DTMF (ITU-T Q.23 Specification) tone packets on request
diff --git a/gst/dtmf/gstdtmfsrc.h b/gst/dtmf/gstdtmfsrc.h
index 1d7c5ca0b..aa5d35a61 100644
--- a/gst/dtmf/gstdtmfsrc.h
+++ b/gst/dtmf/gstdtmfsrc.h
@@ -42,13 +42,6 @@ G_BEGIN_DECLS
 typedef struct _GstDTMFSrc GstDTMFSrc;
 typedef struct _GstDTMFSrcClass GstDTMFSrcClass;
 
-/**
- * GstDTMFSrc:
- * @element: the parent element.
- *
- * The opaque #GstDTMFSrc data structure.
- */
-
 enum _GstDTMFEventType
 {
   DTMF_EVENT_TYPE_START,
@@ -69,6 +62,12 @@ struct _GstDTMFSrcEvent
 
 typedef struct _GstDTMFSrcEvent GstDTMFSrcEvent;
 
+/**
+ * GstDTMFSrc:
+ * @element: the parent element.
+ *
+ * The opaque #GstDTMFSrc data structure.
+ */
 struct _GstDTMFSrc
 {
   /*< private >*/
diff --git a/gst/dtmf/gstrtpdtmfdepay.c b/gst/dtmf/gstrtpdtmfdepay.c
index 237792b38..85e7d1c27 100644
--- a/gst/dtmf/gstrtpdtmfdepay.c
+++ b/gst/dtmf/gstrtpdtmfdepay.c
@@ -21,7 +21,6 @@
  */
 /**
  * SECTION:element-rtpdtmfdepay
- * @short_description: Transforms RFC 4733/2833 RTP dtmf packets into sound
  * @see_also: rtpdtmfsrc, rtpdtmfmux
  *
  * This element takes RTP DTMF packets and produces sound. It also emits a
diff --git a/gst/dtmf/gstrtpdtmfsrc.c b/gst/dtmf/gstrtpdtmfsrc.c
index 3efa46024..738be59e3 100644
--- a/gst/dtmf/gstrtpdtmfsrc.c
+++ b/gst/dtmf/gstrtpdtmfsrc.c
@@ -25,7 +25,6 @@
 
 /**
  * SECTION:element-rtpdtmfsrc
- * @short_description: Generates RTP DTMF packets
  * @see_also: dtmfsrc, rtpdtmfdepay, rtpdtmfmux
  *
  * The RTPDTMFSrc element generates RTP DTMF (RFC 2833) event packets on request
diff --git a/gst/rtpmanager/rtpjitterbuffer.c b/gst/rtpmanager/rtpjitterbuffer.c
index 52b774b6b..123d26f0c 100644
--- a/gst/rtpmanager/rtpjitterbuffer.c
+++ b/gst/rtpmanager/rtpjitterbuffer.c
@@ -569,7 +569,7 @@ rtp_jitter_buffer_get_ts_diff (RTPJitterBuffer * jbuf)
  * @clock_rate: clock-rate of @rtptime
  * @last_rtptime: last seen rtptime.
  *
- * Returns the relation between the RTP timestamp and the GStreamer timestamp
+ * Calculates the relation between the RTP timestamp and the GStreamer timestamp
  * used for constructing timestamps.
  *
  * For extended RTP timestamp @rtptime with a clock-rate of @clock_rate,
diff --git a/gst/rtpmux/gstrtpdtmfmux.c b/gst/rtpmux/gstrtpdtmfmux.c
index 9928cc6e7..f98d7a04c 100644
--- a/gst/rtpmux/gstrtpdtmfmux.c
+++ b/gst/rtpmux/gstrtpdtmfmux.c
@@ -25,7 +25,6 @@
 
 /**
  * SECTION:element-rtpdtmfmux
- * @short_description: mixes RTP DTMF streams into other RTP streams
  * @see_also: rtpdtmfsrc, dtmfsrc
  *
  * The RTPDTMFMuxer mixes/muxes RTP DTMF stream(s) into other RTP
diff --git a/gst/rtpmux/gstrtpmux.c b/gst/rtpmux/gstrtpmux.c
index bdf29cf7f..23730b96e 100644
--- a/gst/rtpmux/gstrtpmux.c
+++ b/gst/rtpmux/gstrtpmux.c
@@ -25,8 +25,6 @@
 
 /**
  * SECTION:element-rtpmux
- * @short_description: Muxer that takes one or several RTP streams
- * and muxes them to a single rtp stream.
  *
  * The rtp muxer takes multiple RTP streams having the same clock-rate and
  * muxes into a single stream with a single SSRC.
diff --git a/gst/selector/gstinputselector.c b/gst/selector/gstinputselector.c
index 6184b65f2..ec1ae542a 100644
--- a/gst/selector/gstinputselector.c
+++ b/gst/selector/gstinputselector.c
@@ -802,8 +802,11 @@ gst_input_selector_class_init (GstInputSelectorClass * klass)
    * If @pad is the same as the current active pad, the element will cancel any
    * previous block without adjusting segments.
    *
-   * Since: 0.10.7 the signal changed from accepting the pad name to the pad
-   * object.
+   * <note><simpara>
+   * the signal changed from accepting the pad name to the pad object.
+   * </simpara></note>
+   *
+   * Since: 0.10.7
    */
   gst_input_selector_signals[SIGNAL_SWITCH] =
       g_signal_new ("switch", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,