From 670596abdbcf74915c34b919e6b91135dbc8912b Mon Sep 17 00:00:00 2001 From: Mathieu Duponchelle Date: Wed, 17 Feb 2021 18:35:33 +0100 Subject: [PATCH] docs: standardize debugutils documentation * add a SECTION comment * Misc cleanup / typo fixes / addition of links Part-of: --- gst/gstdebugutils.c | 15 +++++++++++++-- gst/gstdebugutils.h | 20 ++++++++++++-------- 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/gst/gstdebugutils.c b/gst/gstdebugutils.c index e501c61..8ca334a 100644 --- a/gst/gstdebugutils.c +++ b/gst/gstdebugutils.c @@ -34,6 +34,17 @@ * caps (simple caps = one line) */ +/** + * SECTION: debugutils + * @title: Debugging utilities + * @short_description: A set of utilities for debugging and development + * + * These utility functions help with generating dot graphs which can + * be rendered with [graphviz] to multiple formats. + * + * [graphviz]: https://graphviz.org/ + */ + #include "gst_private.h" #include "gstdebugutils.h" @@ -799,7 +810,7 @@ debug_dump_footer (GString * str) * @details: type of #GstDebugGraphDetails to use * * To aid debugging applications one can use this method to obtain the whole - * network of gstreamer elements that form the pipeline into an dot file. + * network of gstreamer elements that form the pipeline into a dot file. * This data can be processed with graphviz to get an image. * * Returns: (transfer full): a string containing the pipeline in graphviz @@ -828,7 +839,7 @@ gst_debug_bin_to_dot_data (GstBin * bin, GstDebugGraphDetails details) * @file_name: (type filename): output base filename (e.g. "myplayer") * * To aid debugging applications one can use this method to write out the whole - * network of gstreamer elements that form the pipeline into an dot file. + * network of gstreamer elements that form the pipeline into a dot file. * This file can be processed with graphviz to get an image. * * ``` shell diff --git a/gst/gstdebugutils.h b/gst/gstdebugutils.h index 3808fc6..6a2caa9 100644 --- a/gst/gstdebugutils.h +++ b/gst/gstdebugutils.h @@ -80,17 +80,21 @@ void gst_debug_bin_to_dot_file_with_ts (GstBin *bin, GstDebugGraphDetails detail * @file_name: output base filename (e.g. "myplayer") * * To aid debugging applications one can use this method to write out the whole - * network of gstreamer elements that form the pipeline into an dot file. + * network of gstreamer elements that form the pipeline into a dot file. * This file can be processed with graphviz to get an image, like this: - * |[ - * dot -Tpng -oimage.png graph_lowlevel.dot - * ]| - * There is also a utility called xdot which allows you to view the dot file + * + * ``` shell + * dot -Tpng -oimage.png graph_lowlevel.dot + * ``` + * + * There is also a utility called [xdot] which allows you to view the dot file * directly without converting it first. * - * The macro is only active if the environment variable GST_DEBUG_DUMP_DOT_DIR - * is set to a basepath (e.g. /tmp), and the GStreamer debugging subsystem is - * enabled (i.e., no use of `./configure --disable-gst-debug') + * The macro is only active if the environment variable `GST_DEBUG_DUMP_DOT_DIR` + * is set to a basepath (e.g. `/tmp`), and the GStreamer debugging subsystem is + * enabled (i.e., no use of `./configure --disable-gst-debug`) + * + * [xdot]: https://pypi.org/project/xdot/ */ #define GST_DEBUG_BIN_TO_DOT_FILE(bin, details, file_name) gst_debug_bin_to_dot_file (bin, details, file_name) -- 2.7.4