From 2df9f6e5ce49f975cecfb94cd925cb83b3552522 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Mon, 22 Oct 2018 11:47:32 +0200 Subject: [PATCH] docs: Port all docstring to gtk-doc markdown --- ext/a52dec/gsta52dec.c | 6 +++--- ext/amrnb/amrnbdec.c | 10 +++++----- ext/amrnb/amrnbenc.c | 10 +++++----- ext/amrwbdec/amrwbdec.c | 8 ++++---- ext/cdio/gstcdiocddasrc.c | 36 +++++++++++++----------------------- ext/x264/gstx264enc.c | 29 ++++++++++++++--------------- gst/asfdemux/gstasfdemux.h | 8 ++++---- gst/asfdemux/gstrtspwms.c | 1 + gst/realmedia/gstrdtbuffer.h | 11 +++++------ gst/realmedia/rademux.c | 8 ++++---- gst/realmedia/rdtmanager.c | 1 + gst/realmedia/rtspreal.c | 1 + gst/xingmux/gstxingmux.c | 8 ++++---- 13 files changed, 64 insertions(+), 73 deletions(-) diff --git a/ext/a52dec/gsta52dec.c b/ext/a52dec/gsta52dec.c index 450152a724..ccbf4d5384 100644 --- a/ext/a52dec/gsta52dec.c +++ b/ext/a52dec/gsta52dec.c @@ -19,18 +19,18 @@ /** * SECTION:element-a52dec + * @title: a52dec * * Dolby Digital (AC-3) audio decoder. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 dvdreadsrc title=1 ! mpegpsdemux ! a52dec ! audioconvert ! audioresample ! autoaudiosink * ]| Play audio part of a dvd title. * |[ * gst-launch-1.0 filesrc location=abc.ac3 ! ac3parse ! a52dec ! audioconvert ! audioresample ! autoaudiosink * ]| Decode and play a stand alone AC-3 file. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/amrnb/amrnbdec.c b/ext/amrnb/amrnbdec.c index 8f2c422990..c5f2774c0e 100644 --- a/ext/amrnb/amrnbdec.c +++ b/ext/amrnb/amrnbdec.c @@ -19,17 +19,17 @@ /** * SECTION:element-amrnbdec + * @title: amrnbdec * @see_also: #GstAmrnbEnc, #GstAmrParse * - * AMR narrowband decoder based on the + * AMR narrowband decoder based on the * opencore codec implementation. - * - * - * Example launch line + * + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=abc.amr ! amrparse ! amrnbdec ! audioconvert ! audioresample ! autoaudiosink * ]| - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/amrnb/amrnbenc.c b/ext/amrnb/amrnbenc.c index 2f72b9fb74..9c0f28560f 100644 --- a/ext/amrnb/amrnbenc.c +++ b/ext/amrnb/amrnbenc.c @@ -19,19 +19,19 @@ /** * SECTION:element-amrnbenc + * @title: amrnbenc * @see_also: #GstAmrnbDec, #GstAmrnbParse * - * AMR narrowband encoder based on the + * AMR narrowband encoder based on the * opencore codec implementation. - * - * - * Example launch line + * + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=abc.wav ! wavparse ! audioconvert ! audioresample ! amrnbenc ! filesink location=abc.amr * ]| * Please note that the above stream misses the header, that is needed to play * the stream. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/amrwbdec/amrwbdec.c b/ext/amrwbdec/amrwbdec.c index cf05d95300..7832036c54 100644 --- a/ext/amrwbdec/amrwbdec.c +++ b/ext/amrwbdec/amrwbdec.c @@ -19,17 +19,17 @@ /** * SECTION:element-amrwbdec + * @title: amrwbdec * @see_also: #GstAmrwbEnc * - * AMR wideband decoder based on the + * AMR wideband decoder based on the * opencore codec implementation. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=abc.amr ! amrparse ! amrwbdec ! audioconvert ! audioresample ! autoaudiosink * ]| - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/cdio/gstcdiocddasrc.c b/ext/cdio/gstcdiocddasrc.c index 0990b500ac..c82d0bd668 100644 --- a/ext/cdio/gstcdiocddasrc.c +++ b/ext/cdio/gstcdiocddasrc.c @@ -19,38 +19,29 @@ /** * SECTION:element-cdiocddasrc + * @title: cdiocddasrc * @see_also: GstCdParanoiaSrc, GstAudioCdSrc * - * - * * cdiocddasrc reads and extracts raw audio from Audio CDs. It can operate * in one of two modes: - * - * - * treat each track as a separate stream, counting time from the start + * + * * treat each track as a separate stream, counting time from the start * of the track to the end of the track and posting EOS at the end of * a track, or - * - * - * treat the entire disc as one stream, counting time from the start of + * * treat the entire disc as one stream, counting time from the start of * the first track to the end of the last track, posting EOS only at * the end of the last track. - * - * - * - * + * * With a recent-enough version of libcdio, the element will extract * CD-TEXT if this is supported by the CD-drive and CD-TEXT information * is available on the CD. The information will be posted on the bus in * form of a tag message. - * - * + * * When opened, the element will also calculate a CDDB disc ID and a * MusicBrainz disc ID, which applications can use to query online * databases for artist/title information. These disc IDs will also be * posted on the bus as part of the tag messages. - * - * + * * cdiocddasrc supports the GstUriHandler interface, so applications can use * playbin with cdda://<track-number> URIs for playback (they will have * to connect to playbin's notify::source signal and set the device on the @@ -58,16 +49,15 @@ * Applications should use seeks in "track" format to switch between different * tracks of the same CD (passing a new cdda:// URI to playbin involves opening * and closing the CD device, which is much slower). - * - * Example launch line - * - * + * + * ## Example launch line + * + * |[ * gst-launch-1.0 cdiocddasrc track=5 device=/dev/cdrom ! audioconvert ! vorbisenc ! oggmux ! filesink location=track5.ogg - * + * ]| * This pipeline extracts track 5 of the audio CD and encodes it into an * Ogg/Vorbis file. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/x264/gstx264enc.c b/ext/x264/gstx264enc.c index f313b21113..54bd7a1c50 100644 --- a/ext/x264/gstx264enc.c +++ b/ext/x264/gstx264enc.c @@ -22,6 +22,7 @@ /** * SECTION:element-x264enc + * @title: x264enc * @see_also: faac * * This element encodes raw video into H264 compressed data, @@ -49,21 +50,19 @@ * applied, followed by the user-set properties, fast first pass restrictions and * finally the profile restrictions. * - * Some settings, including the default settings, may lead to quite - * some latency (i.e. frame buffering) in the encoder. This may cause problems - * with pipeline stalling in non-trivial pipelines, because the encoder latency - * is often considerably higher than the default size of a simple queue - * element. Such problems are caused by one of the queues in the other - * non-x264enc streams/branches filling up and blocking upstream. They can - * be fixed by relaxing the default time/size/buffer limits on the queue - * elements in the non-x264 branches, or using a (single) multiqueue element - * for all branches. Also see the last example below. You can also work around - * this problem by setting the tune=zerolatency property, but this will affect - * overall encoding quality so may not be appropriate for your use case. - * + * > Some settings, including the default settings, may lead to quite + * > some latency (i.e. frame buffering) in the encoder. This may cause problems + * > with pipeline stalling in non-trivial pipelines, because the encoder latency + * > is often considerably higher than the default size of a simple queue + * > element. Such problems are caused by one of the queues in the other + * > non-x264enc streams/branches filling up and blocking upstream. They can + * > be fixed by relaxing the default time/size/buffer limits on the queue + * > elements in the non-x264 branches, or using a (single) multiqueue element + * > for all branches. Also see the last example below. You can also work around + * > this problem by setting the tune=zerolatency property, but this will affect + * > overall encoding quality so may not be appropriate for your use case. * - * - * Example pipeline + * ## Example pipeline * |[ * gst-launch-1.0 -v videotestsrc num-buffers=1000 ! x264enc qp-min=18 ! \ * avimux ! filesink location=videotestsrc.avi @@ -92,7 +91,7 @@ * specific settings are needed in this case to avoid pipeline stalling. * Depending on goals and context, other approaches are possible, e.g. * tune=zerolatency might be configured, or queue sizes increased. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/asfdemux/gstasfdemux.h b/gst/asfdemux/gstasfdemux.h index 953b4963d0..4e3dde3692 100644 --- a/gst/asfdemux/gstasfdemux.h +++ b/gst/asfdemux/gstasfdemux.h @@ -28,7 +28,7 @@ #include "asfheaders.h" G_BEGIN_DECLS - + #define GST_TYPE_ASF_DEMUX \ (gst_asf_demux_get_type()) #define GST_ASF_DEMUX(obj) \ @@ -70,7 +70,7 @@ enum _GstASF3DMode GST_ASF_3D_SIDE_BY_SIDE_HALF_RL = 0x02, GST_ASF_3D_TOP_AND_BOTTOM_HALF_LR = 0x03, GST_ASF_3D_TOP_AND_BOTTOM_HALF_RL = 0x04, - GST_ASF_3D_DUAL_STREAM = 0x0D, /**< Full format*/ + GST_ASF_3D_DUAL_STREAM = 0x0D, /*< Full format*/ }; typedef struct @@ -140,7 +140,7 @@ typedef struct /* extended stream properties (optional) */ AsfStreamExtProps ext_props; - + gboolean inspect_payload; } AsfStream; @@ -231,7 +231,7 @@ struct _GstASFDemux { GstClockTime sidx_interval; /* interval between entries in ns */ guint sidx_num_entries; /* number of index entries */ AsfSimpleIndexEntry *sidx_entries; /* packet number for each entry */ - + GSList *other_streams; /* remember streams that are in header but have unknown type */ /* For reverse playback */ diff --git a/gst/asfdemux/gstrtspwms.c b/gst/asfdemux/gstrtspwms.c index c864287e6a..9d045a8d3a 100644 --- a/gst/asfdemux/gstrtspwms.c +++ b/gst/asfdemux/gstrtspwms.c @@ -20,6 +20,7 @@ /** * SECTION:element-rtspwms + * @title: rtspwms * * A WMS RTSP extension */ diff --git a/gst/realmedia/gstrdtbuffer.h b/gst/realmedia/gstrdtbuffer.h index 1ff9c93984..fd1e067f83 100644 --- a/gst/realmedia/gstrdtbuffer.h +++ b/gst/realmedia/gstrdtbuffer.h @@ -26,8 +26,7 @@ #include G_BEGIN_DECLS - -/** +/** * GstRDTType: * @GST_RDT_TYPE_INVALID: * @GST_RDT_TYPE_ASMACTION: @@ -63,7 +62,7 @@ typedef enum /** * GST_RDT_IS_DATA_TYPE: * @t: the #GstRDTType to check - * + * * Check if @t is a data packet type. */ #define GST_RDT_IS_DATA_TYPE(t) ((t) < 0xff00) @@ -75,14 +74,14 @@ typedef struct _GstRDTPacket GstRDTPacket; * @buffer: pointer to RDT buffer * @offset: offset of packet in buffer data * - * Data structure that points to a packet at @offset in @buffer. + * Data structure that points to a packet at @offset in @buffer. * The size of the structure is made public to allow stack allocations. */ struct _GstRDTPacket -{ +{ GstBuffer *buffer; guint offset; - + /*< private >*/ GstRDTType type; /* type of current packet */ guint16 length; /* length of current packet in bytes */ diff --git a/gst/realmedia/rademux.c b/gst/realmedia/rademux.c index 3dadcc5082..d2ca9ae57e 100644 --- a/gst/realmedia/rademux.c +++ b/gst/realmedia/rademux.c @@ -19,11 +19,11 @@ /** * SECTION:element-rademux + * @title: rademux * * Demuxes/parses a RealAudio (.ra) file or stream into compressed audio. - * - * - * Example launch line + * + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=interview.ra ! rademux ! avdec_real_288 ! audioconvert ! audioresample ! autoaudiosink * ]| Read a RealAudio file and decode it and output it to the soundcard using @@ -32,7 +32,7 @@ * gst-launch-1.0 souphttpsrc location=http://www.example.org/interview.ra ! rademux ! ac3parse ! a52dec ! audioconvert ! audioresample ! autoaudiosink * ]| Stream RealAudio data containing AC3 (dnet) compressed audio and decode it * and output it to the soundcard. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/realmedia/rdtmanager.c b/gst/realmedia/rdtmanager.c index 48bc5ef4a7..742a6e2687 100644 --- a/gst/realmedia/rdtmanager.c +++ b/gst/realmedia/rdtmanager.c @@ -44,6 +44,7 @@ /** * SECTION:element-rdtmanager + * @title: rdtmanager * @see_also: GstRtspSrc * * A simple RTP session manager used internally by rtspsrc. diff --git a/gst/realmedia/rtspreal.c b/gst/realmedia/rtspreal.c index 8af70bec3a..fab3a4764f 100644 --- a/gst/realmedia/rtspreal.c +++ b/gst/realmedia/rtspreal.c @@ -20,6 +20,7 @@ /** * SECTION:element-rtspreal + * @title: rtspreal * * A RealMedia RTSP extension */ diff --git a/gst/xingmux/gstxingmux.c b/gst/xingmux/gstxingmux.c index b0809aa94a..38c1abbed5 100644 --- a/gst/xingmux/gstxingmux.c +++ b/gst/xingmux/gstxingmux.c @@ -23,21 +23,21 @@ /** * SECTION:element-xingmux + * @title: xingmux * * xingmux adds a Xing header to MP3 files. This contains information about the duration and size * of the file and a seek table and is very useful for getting an almost correct duration and better * seeking on VBR MP3 files. - * + * * This element will remove any existing Xing, LAME or VBRI headers from the beginning of the file. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 audiotestsrc num-buffers=1000 ! audioconvert ! lamemp3enc ! xingmux ! filesink location=test.mp3 * gst-launch-1.0 filesrc location=test.mp3 ! xingmux ! filesink location=test2.mp3 * gst-launch-1.0 filesrc location=test.mp3 ! mp3parse ! xingmux ! filesink location=test2.mp3 * ]| - * + * */ #ifdef HAVE_CONFIG_H