From adb4cb86918176c34f4942795305a017416f73c7 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Sat, 24 Sep 2022 16:30:50 -0300 Subject: [PATCH] tracers: Fix documentation comment using gtk-doc style So the online documentation works --- utils/tracers/src/buffer_lateness/imp.rs | 73 +++++++++++----------- utils/tracers/src/pipeline_snapshot/imp.rs | 58 +++++++++-------- utils/tracers/src/queue_levels/imp.rs | 72 +++++++++++---------- 3 files changed, 107 insertions(+), 96 deletions(-) diff --git a/utils/tracers/src/buffer_lateness/imp.rs b/utils/tracers/src/buffer_lateness/imp.rs index c16cb1ec..0c4ef855 100644 --- a/utils/tracers/src/buffer_lateness/imp.rs +++ b/utils/tracers/src/buffer_lateness/imp.rs @@ -6,41 +6,44 @@ // // SPDX-License-Identifier: MPL-2.0 -/// This tracer provides an easy way to collect lateness of each buffer when it is pushed out of a -/// pad in live pipelines. -/// -/// Example: -/// -/// ```console -/// $ GST_TRACERS='buffer-lateness(file="/tmp/buffer_lateness.log")' gst-launch-1.0 audiotestsrc is-live=true ! queue ! fakesink -/// ``` -/// -/// The generated file is a CSV file of the format -/// -/// ```csv -/// timestamp,element:pad name,pad pointer,buffer clock time,pipeline clock time,lateness,min latency -/// ``` -/// -/// ## Parameters -/// -/// ### `file` -/// -/// Specifies the path to the file that will collect the CSV file with the buffer lateness. -/// -/// By default the file is written to `/tmp/buffer_lateness.log`. -/// -/// ### `include-filter` -/// -/// Specifies a regular expression for the `element:pad` names that should be included. -/// -/// By default this is not set. -/// -/// ### `exclude-filter` -/// -/// Specifies a regular expression for the `element:pad` names that should **not** be included. -/// -/// By default this is not set. -/// +/** + * tracer-buffer-lateness: + * + * This tracer provides an easy way to collect lateness of each buffer when it is pushed out of a + * pad in live pipelines. + * + * Example: + * + * ```console + * $ GST_TRACERS='buffer-lateness(file="/tmp/buffer_lateness.log")' gst-launch-1.0 audiotestsrc is-live=true ! queue ! fakesink + * ``` + * + * The generated file is a CSV file of the format + * + * ```csv + * timestamp,element:pad name,pad pointer,buffer clock time,pipeline clock time,lateness,min latency + * ``` + * + * ## Parameters + * + * ### `file` + * + * Specifies the path to the file that will collect the CSV file with the buffer lateness. + * + * By default the file is written to `/tmp/buffer_lateness.log`. + * + * ### `include-filter` + * + * Specifies a regular expression for the `element:pad` names that should be included. + * + * By default this is not set. + * + * ### `exclude-filter` + * + * Specifies a regular expression for the `element:pad` names that should **not** be included. + * + * By default this is not set. + */ use std::collections::HashMap; use std::path::PathBuf; use std::str::FromStr; diff --git a/utils/tracers/src/pipeline_snapshot/imp.rs b/utils/tracers/src/pipeline_snapshot/imp.rs index da5e7136..087d961e 100644 --- a/utils/tracers/src/pipeline_snapshot/imp.rs +++ b/utils/tracers/src/pipeline_snapshot/imp.rs @@ -6,33 +6,37 @@ // // SPDX-License-Identifier: MPL-2.0 -/// This tracer provides an easy way to take a snapshot of all the pipelines without -/// having to modify the application. -/// One just have to load the tracer and send the `SIGUSR1` UNIX signal to take snapshots. -/// It currently only works on UNIX systems. -/// -/// When taking a snapshot pipelines are saved to DOT files, but the tracer may be -/// extended in the future to dump more information. -/// -/// Example: -/// -/// ```console -/// $ GST_TRACERS="pipeline-snapshot" GST_DEBUG_DUMP_DOT_DIR=. gst-launch-1.0 audiotestsrc ! fakesink -/// ``` -/// You can then trigger a snapshot using: -/// ```console -/// $ kill -SIGUSR1 $(pidof gst-launch-1.0) -/// ``` -/// -/// Parameters can be passed to configure the tracer: -/// - `dot-prefix` (string, default: "pipeline-snapshot-"): when dumping pipelines to a `dot` file each file is named `$prefix$pipeline_name.dot`. -/// - `dot-ts` (boolean, default: "true"): if the current timestamp should be added as a prefix to each pipeline `dot` file. -/// -/// Example: -/// -/// ```console -/// $ GST_TRACERS="pipeline-snapshot(dot-prefix="badger-",dot-ts=false)" GST_DEBUG_DUMP_DOT_DIR=. gst-launch-1.0 audiotestsrc ! fakesink -/// ``` +/** + * tracer-pipeline-snapshot: + * + * This tracer provides an easy way to take a snapshot of all the pipelines without + * having to modify the application. + * One just have to load the tracer and send the `SIGUSR1` UNIX signal to take snapshots. + * It currently only works on UNIX systems. + * + * When taking a snapshot pipelines are saved to DOT files, but the tracer may be + * extended in the future to dump more information. + * + * Example: + * + * ```console + * $ GST_TRACERS="pipeline-snapshot" GST_DEBUG_DUMP_DOT_DIR=. gst-launch-1.0 audiotestsrc ! fakesink + * ``` + * You can then trigger a snapshot using: + * ```console + * $ kill -SIGUSR1 $(pidof gst-launch-1.0) + * ``` + * + * Parameters can be passed to configure the tracer: + * - `dot-prefix` (string, default: "pipeline-snapshot-"): when dumping pipelines to a `dot` file each file is named `$prefix$pipeline_name.dot`. + * - `dot-ts` (boolean, default: "true"): if the current timestamp should be added as a prefix to each pipeline `dot` file. + * + * Example: + * + * ```console + * $ GST_TRACERS="pipeline-snapshot(dot-prefix="badger-",dot-ts=false)" GST_DEBUG_DUMP_DOT_DIR=. gst-launch-1.0 audiotestsrc ! fakesink + * ``` + */ use std::collections::HashMap; use std::str::FromStr; use std::sync::{Arc, Mutex}; diff --git a/utils/tracers/src/queue_levels/imp.rs b/utils/tracers/src/queue_levels/imp.rs index 145e00fb..681d6d57 100644 --- a/utils/tracers/src/queue_levels/imp.rs +++ b/utils/tracers/src/queue_levels/imp.rs @@ -6,40 +6,44 @@ // // SPDX-License-Identifier: MPL-2.0 -/// This tracer provides an easy way to collect queue levels over time of all queues inside a -/// pipeline. -/// -/// Example: -/// -/// ```console -/// $ GST_TRACERS='queue-levels(file="/tmp/queue_levels.log")' gst-launch-1.0 audiotestsrc ! queue ! fakesink -/// ``` -/// -/// The generated file is a CSV file of the format -/// -/// ```csv -/// timestamp,queue name,queue pointer,cur-level-bytes,cur-level-time,cur-level-buffers,max-size-bytes,max-size-time,max-size-buffers -/// ``` -/// -/// ## Parameters -/// -/// ### `file` -/// -/// Specifies the path to the file that will collect the CSV file with the queue levels. -/// -/// By default the file is written to `/tmp/queue_levels.log`. -/// -/// ### `include-filter` -/// -/// Specifies a regular expression for the queue object names that should be included. -/// -/// By default this is not set. -/// -/// ### `exclude-filter` -/// -/// Specifies a regular expression for the queue object names that should **not** be included. -/// -/// By default this is not set. +/** + * tracer-queue-levels: + * + * This tracer provides an easy way to collect queue levels over time of all queues inside a + * pipeline. + * + * Example: + * + * ```console + * $ GST_TRACERS='queue-levels(file="/tmp/queue_levels.log")' gst-launch-1.0 audiotestsrc ! queue ! fakesink + * ``` + * + * The generated file is a CSV file of the format + * + * ```csv + * timestamp,queue name,queue pointer,cur-level-bytes,cur-level-time,cur-level-buffers,max-size-bytes,max-size-time,max-size-buffers + * ``` + * + * ## Parameters + * + * ### `file` + * + * Specifies the path to the file that will collect the CSV file with the queue levels. + * + * By default the file is written to `/tmp/queue_levels.log`. + * + * ### `include-filter` + * + * Specifies a regular expression for the queue object names that should be included. + * + * By default this is not set. + * + * ### `exclude-filter` + * + * Specifies a regular expression for the queue object names that should **not** be included. + * + * By default this is not set. + */ use std::collections::HashMap; use std::path::PathBuf; use std::str::FromStr;