From 35da463618f78532f2313e7584b36761bd35a69b Mon Sep 17 00:00:00 2001 From: Stefan Sauer Date: Tue, 18 Feb 2014 21:44:24 +0100 Subject: [PATCH] docs: use the gtk-doc syntax to link to properties Don't use docbook unless needed. Also stip other docbook tags in the the files we fix. --- gst/debugutils/gstcapssetter.c | 38 ++++------- gst/isomp4/gstqtmux-doc.c | 152 +++++++++++++---------------------------- gst/isomp4/gstqtmux.c | 26 ++++--- gst/level/gstlevel.c | 10 ++- gst/replaygain/gstrganalysis.c | 6 +- gst/replaygain/gstrgvolume.c | 35 ++++------ 6 files changed, 95 insertions(+), 172 deletions(-) diff --git a/gst/debugutils/gstcapssetter.c b/gst/debugutils/gstcapssetter.c index dcfabe2..e6573bb 100644 --- a/gst/debugutils/gstcapssetter.c +++ b/gst/debugutils/gstcapssetter.c @@ -20,34 +20,24 @@ /** * SECTION:element-capssetter * - * - * - * Sets or merges caps on a stream's buffers. - * That is, a buffer's caps are updated using (fields of) - * caps. Note that this may - * contain multiple structures (though not likely recommended), but each - * of these must be fixed (or will otherwise be rejected). - * - * - * If join - * is TRUE, then the incoming caps' mime-type is compared to the mime-type(s) - * of provided caps and only matching structure(s) are considered for updating. - * - * - * If replace - * is TRUE, then any caps update is preceded by clearing existing fields, - * making provided fields (as a whole) replace incoming ones. - * Otherwise, no clearing is performed, in which case provided fields are - * added/merged onto incoming caps - * - * + * Sets or merges caps on a stream's buffers. That is, a buffer's caps are + * updated using (fields of) #GstCapsSetter:caps. Note that this may contain + * multiple structures (though not likely recommended), but each of these must + * be fixed (or will otherwise be rejected). + * + * If #GstCapsSetter:join is %TRUE, then the incoming caps' mime-type is + * compared to the mime-type(s) of provided caps and only matching structure(s) + * are considered for updating. + * + * If #GstCapsSetter:replace is %TRUE, then any caps update is preceded by + * clearing existing fields, making provided fields (as a whole) replace + * incoming ones. Otherwise, no clearing is performed, in which case provided + * fields are added/merged onto incoming caps + * * Although this element might mainly serve as debug helper, * it can also practically be used to correct a faulty pixel-aspect-ratio, * or to modify a yuv fourcc value to effectively swap chroma components or such * alike. - * - * - * */ diff --git a/gst/isomp4/gstqtmux-doc.c b/gst/isomp4/gstqtmux-doc.c index 4c89197..3bde328 100644 --- a/gst/isomp4/gstqtmux-doc.c +++ b/gst/isomp4/gstqtmux-doc.c @@ -65,35 +65,21 @@ * The fragmented file features defined (only) in ISO Base Media are used by * ISMV files making up (a.o.) Smooth Streaming (ismlmux). * - * A few properties (movie-timescale, - * trak-timescale) allow adjusting - * some technical parameters, which might be useful in (rare) cases to resolve - * compatibility issues in some situations. + * A few properties (#GstMp4Mux:movie-timescale, #GstMp4Mux:trak-timescale) + * allow adjusting some technical parameters, which might be useful in (rare) + * cases to resolve compatibility issues in some situations. * * Some other properties influence the result more fundamentally. - * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, - * somewhat contrary to this usually being called "the header". - * However, a faststart file will - * (with some effort) arrange this to be located near start of the file, - * which then allows it e.g. to be played while downloading. - * Alternatively, rather than having one chunk of metadata at start (or end), - * there can be some metadata at start and most of the other data can be spread - * out into fragments of fragment-duration. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the + * file, somewhat contrary to this usually being called "the header". + * However, a #GstMp4Mux:faststart file will (with some effort) arrange this to + * be located near start of the file, which then allows it e.g. to be played + * while downloading. Alternatively, rather than having one chunk of metadata at + * start (or end), there can be some metadata at start and most of the other + * data can be spread out into fragments of #GstMp4Mux:fragment-duration. * If such fragmented layout is intended for streaming purposes, then - * streamable allows foregoing to add - * index metadata (at the end of file). - * - * dts-method allows selecting a - * method for managing input timestamps (stay tuned for 0.11 to have this - * automagically settled). The default delta/duration method should handle nice - * (aka perfect streams) just fine, but may experience problems otherwise - * (e.g. input stream with re-ordered B-frames and/or with frame dropping). - * The re-ordering approach re-assigns incoming timestamps in ascending order - * to incoming buffers and offers an alternative in such cases. In cases where - * that might fail, the remaining method can be tried, which is exact and - * according to specs, but might experience playback on not so spec-wise players. - * Note that this latter approach also requires one to enable - * presentation-timestamp. + * #GstMp4Mux:streamable allows foregoing to add index metadata (at the end of + * file). * * * Example pipelines @@ -129,35 +115,21 @@ * The fragmented file features defined (only) in ISO Base Media are used by * ISMV files making up (a.o.) Smooth Streaming (ismlmux). * - * A few properties (movie-timescale, - * trak-timescale) allow adjusting - * some technical parameters, which might be useful in (rare) cases to resolve - * compatibility issues in some situations. + * A few properties (#Gst3GPPMux:movie-timescale, #Gst3GPPMux:trak-timescale) + * allow adjusting some technical parameters, which might be useful in (rare) + * cases to resolve compatibility issues in some situations. * * Some other properties influence the result more fundamentally. * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, - * somewhat contrary to this usually being called "the header". - * However, a faststart file will - * (with some effort) arrange this to be located near start of the file, - * which then allows it e.g. to be played while downloading. - * Alternatively, rather than having one chunk of metadata at start (or end), - * there can be some metadata at start and most of the other data can be spread - * out into fragments of fragment-duration. - * If such fragmented layout is intended for streaming purposes, then - * streamable allows foregoing to add - * index metadata (at the end of file). - * - * dts-method allows selecting a - * method for managing input timestamps (stay tuned for 0.11 to have this - * automagically settled). The default delta/duration method should handle nice - * (aka perfect streams) just fine, but may experience problems otherwise - * (e.g. input stream with re-ordered B-frames and/or with frame dropping). - * The re-ordering approach re-assigns incoming timestamps in ascending order - * to incoming buffers and offers an alternative in such cases. In cases where - * that might fail, the remaining method can be tried, which is exact and - * according to specs, but might experience playback on not so spec-wise players. - * Note that this latter approach also requires one to enable - * presentation-timestamp. + * somewhat contrary to this usually being called "the header". However, a + * #Gst3GPPMux:faststart file will (with some effort) arrange this to be located + * near start of the file, which then allows it e.g. to be played while + * downloading. Alternatively, rather than having one chunk of metadata at start + * (or end), there can be some metadata at start and most of the other data can + * be spread out into fragments of #Gst3GPPMux:fragment-duration. If such + * fragmented layout is intended for streaming purposes, then + * #Gst3GPPMux:streamable allows foregoing to add index metadata (at the end of + * file). * * * Example pipelines @@ -193,35 +165,21 @@ * The fragmented file features defined (only) in ISO Base Media are used by * ISMV files making up (a.o.) Smooth Streaming (ismlmux). * - * A few properties (movie-timescale, - * trak-timescale) allow adjusting - * some technical parameters, which might be useful in (rare) cases to resolve - * compatibility issues in some situations. + * A few properties (#GstMJ2Mux:movie-timescale, #GstMJ2Mux:trak-timescale) + * allow adjusting some technical parameters, which might be useful in (rare) + * cases to resolve compatibility issues in some situations. * * Some other properties influence the result more fundamentally. * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, - * somewhat contrary to this usually being called "the header". - * However, a faststart file will - * (with some effort) arrange this to be located near start of the file, - * which then allows it e.g. to be played while downloading. - * Alternatively, rather than having one chunk of metadata at start (or end), - * there can be some metadata at start and most of the other data can be spread - * out into fragments of fragment-duration. - * If such fragmented layout is intended for streaming purposes, then - * streamable allows foregoing to add - * index metadata (at the end of file). - * - * dts-method allows selecting a - * method for managing input timestamps (stay tuned for 0.11 to have this - * automagically settled). The default delta/duration method should handle nice - * (aka perfect streams) just fine, but may experience problems otherwise - * (e.g. input stream with re-ordered B-frames and/or with frame dropping). - * The re-ordering approach re-assigns incoming timestamps in ascending order - * to incoming buffers and offers an alternative in such cases. In cases where - * that might fail, the remaining method can be tried, which is exact and - * according to specs, but might experience playback on not so spec-wise players. - * Note that this latter approach also requires one to enable - * presentation-timestamp. + * somewhat contrary to this usually being called "the header". However, a + * #GstMJ2Mux:faststart file will (with some effort) arrange this to be located + * near start of the file, which then allows it e.g. to be played while + * downloading. Alternatively, rather than having one chunk of metadata at start + * (or end), there can be some metadata at start and most of the other data can + * be spread out into fragments of #GstMJ2Mux:fragment-duration. If such + * fragmented layout is intended for streaming purposes, then + * #GstMJ2Mux:streamable allows foregoing to add index metadata (at the end of + * file). * * * Example pipelines @@ -257,35 +215,21 @@ * The fragmented file features defined (only) in ISO Base Media are used by * ISMV files making up (a.o.) Smooth Streaming (ismlmux). * - * A few properties (movie-timescale, - * trak-timescale) allow adjusting - * some technical parameters, which might be useful in (rare) cases to resolve - * compatibility issues in some situations. + * A few properties (#GstISMLMux:movie-timescale, #GstISMLMux:trak-timescale) + * allow adjusting some technical parameters, which might be useful in (rare) + * cases to resolve compatibility issues in some situations. * * Some other properties influence the result more fundamentally. * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, - * somewhat contrary to this usually being called "the header". - * However, a faststart file will - * (with some effort) arrange this to be located near start of the file, - * which then allows it e.g. to be played while downloading. - * Alternatively, rather than having one chunk of metadata at start (or end), - * there can be some metadata at start and most of the other data can be spread - * out into fragments of fragment-duration. - * If such fragmented layout is intended for streaming purposes, then - * streamable allows foregoing to add - * index metadata (at the end of file). - * - * dts-method allows selecting a - * method for managing input timestamps (stay tuned for 0.11 to have this - * automagically settled). The default delta/duration method should handle nice - * (aka perfect streams) just fine, but may experience problems otherwise - * (e.g. input stream with re-ordered B-frames and/or with frame dropping). - * The re-ordering approach re-assigns incoming timestamps in ascending order - * to incoming buffers and offers an alternative in such cases. In cases where - * that might fail, the remaining method can be tried, which is exact and - * according to specs, but might experience playback on not so spec-wise players. - * Note that this latter approach also requires one to enable - * presentation-timestamp. + * somewhat contrary to this usually being called "the header". However, a + * #GstISMLMux:faststart file will (with some effort) arrange this to be located + * near start of the file, which then allows it e.g. to be played while + * downloading. Alternatively, rather than having one chunk of metadata at start + * (or end), there can be some metadata at start and most of the other data can + * be spread out into fragments of #GstISMLMux:fragment-duration. If such + * fragmented layout is intended for streaming purposes, then + * #GstISMLMux:streamable allows foregoing to add index metadata (at the end of + * file). * * * Example pipelines diff --git a/gst/isomp4/gstqtmux.c b/gst/isomp4/gstqtmux.c index b83d1fe..702fa92 100644 --- a/gst/isomp4/gstqtmux.c +++ b/gst/isomp4/gstqtmux.c @@ -64,23 +64,21 @@ * The fragmented file features defined (only) in ISO Base Media are used by * ISMV files making up (a.o.) Smooth Streaming (ismlmux). * - * A few properties (movie-timescale, - * trak-timescale) allow adjusting - * some technical parameters, which might be useful in (rare) cases to resolve - * compatibility issues in some situations. + * A few properties (#GstQTMux:movie-timescale, #GstQTMux:trak-timescale) allow + * adjusting some technical parameters, which might be useful in (rare) cases to + * resolve compatibility issues in some situations. * * Some other properties influence the result more fundamentally. - * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, - * somewhat contrary to this usually being called "the header". - * However, a faststart file will - * (with some effort) arrange this to be located near start of the file, - * which then allows it e.g. to be played while downloading. - * Alternatively, rather than having one chunk of metadata at start (or end), - * there can be some metadata at start and most of the other data can be spread - * out into fragments of fragment-duration. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the + * file, somewhat contrary to this usually being called "the header". + * However, a #GstQTMux:faststart file will (with some effort) arrange this to + * be located near start of the file, which then allows it e.g. to be played + * while downloading. Alternatively, rather than having one chunk of metadata at + * start (or end), there can be some metadata at start and most of the other + * data can be spread out into fragments of #GstQTMux:fragment-duration. * If such fragmented layout is intended for streaming purposes, then - * streamable allows foregoing to add - * index metadata (at the end of file). + * #GstQTMux:streamable allows foregoing to add index metadata (at the end of + * file). * * * Example pipelines diff --git a/gst/level/gstlevel.c b/gst/level/gstlevel.c index 59943d4..92e0bfe 100644 --- a/gst/level/gstlevel.c +++ b/gst/level/gstlevel.c @@ -76,12 +76,10 @@ * #GValueArray of #gdouble * "decay": * the decaying peak power level in dB for each channel - * the decaying peak level follows the peak level, but starts dropping - * if no new peak is reached after the time given by - * the the time to live. - * When the decaying peak level drops, it does so at the decay rate - * as specified by the - * the peak falloff rate. + * The decaying peak level follows the peak level, but starts dropping if no + * new peak is reached after the time given by the #GstLevel:peak-ttl. + * When the decaying peak level drops, it does so at the decay rate as + * specified by the #GstLevel:peak-falloff. * * * diff --git a/gst/replaygain/gstrganalysis.c b/gst/replaygain/gstrganalysis.c index 3e87953..98c3ca6 100644 --- a/gst/replaygain/gstrganalysis.c +++ b/gst/replaygain/gstrganalysis.c @@ -39,9 +39,9 @@ * their output since they generally save metadata in the file header. * Therefore, it is often necessary that applications read the results in a bus * event handler for the tag message. Obtaining the values this way is always - * needed for album processing - * since the album gain and peak values need to be associated with all tracks of - * an album, not just the last one. + * needed for album processing (see #GstRgAnalysis:num-tracks property) since + * the album gain and peak values need to be associated with all tracks of an + * album, not just the last one. * * * Example launch lines diff --git a/gst/replaygain/gstrgvolume.c b/gst/replaygain/gstrgvolume.c index 05c21e0..d88d5db 100644 --- a/gst/replaygain/gstrgvolume.c +++ b/gst/replaygain/gstrgvolume.c @@ -162,8 +162,7 @@ gst_rg_volume_class_init (GstRgVolumeClass * klass) * * If album mode is enabled but the album gain tag is absent in the stream, * the track gain is used instead. If both gain tags are missing, the value - * of the fallback-gain - * property is used instead. + * of the #GstRgVolume:fallback-gain property is used instead. */ g_object_class_install_property (gobject_class, PROP_ALBUM_MODE, g_param_spec_boolean ("album-mode", "Album mode", @@ -223,24 +222,22 @@ gst_rg_volume_class_init (GstRgVolumeClass * klass) * * Applied gain [dB]. This gain is applied to processed buffer data. * - * This is set to the target - * gain if amplification by that amount can be applied safely. - * "Safely" means that the volume adjustment does not inflict clipping - * distortion. Should this not be the case, the result gain is set to an - * appropriately reduced value (by applying peak normalization). The proposed - * standard calls this "clipping prevention". + * This is set to the #GstRgVolume:target-gain if amplification by that amount + * can be applied safely. "Safely" means that the volume adjustment does not + * inflict clipping distortion. Should this not be the case, the result gain + * is set to an appropriately reduced value (by applying peak normalization). + * The proposed standard calls this "clipping prevention". * * The difference between target and result gain reflects the necessary amount * of reduction. Applications can make use of this information to temporarily - * reduce the pre-amp for - * subsequent streams, as recommended by the ReplayGain standard. + * reduce the #GstRgVolume:pre-amp for subsequent streams, as recommended by + * the ReplayGain standard. * * Note that target and result gain differing for a great majority of streams * indicates a problem: What happens in this case is that most streams receive * peak normalization instead of amplification by the ideal replay gain. To - * prevent this, the pre-amp has - * to be lowered and/or a limiter has to be used which facilitates the use of - * headroom. + * prevent this, the #GstRgVolume:pre-amp has to be lowered and/or a limiter + * has to be used which facilitates the use of #GstRgVolume:headroom. */ g_object_class_install_property (gobject_class, PROP_RESULT_GAIN, g_param_spec_double ("result-gain", "Result-gain", "Applied gain [dB]", @@ -250,18 +247,14 @@ gst_rg_volume_class_init (GstRgVolumeClass * klass) * * Applicable gain [dB]. This gain is supposed to be applied. * - * Depending on the value of the album-mode property and the + * Depending on the value of the #GstRgVolume:album-mode property and the * presence of ReplayGain tags in the stream, this is set according to one of * these simple formulas: * * - * pre-amp + album gain - * of the stream - * pre-amp + track gain - * of the stream - * pre-amp + fallback gain + * #GstRgVolume:pre-amp + album gain of the stream + * #GstRgVolume:pre-amp + track gain of the stream + * #GstRgVolume:pre-amp + #GstRgVolume:fallback-gain * */ g_object_class_install_property (gobject_class, PROP_TARGET_GAIN, -- 2.7.4