docs: standardize debugutils documentation

* add a SECTION comment

* Misc cleanup / typo fixes / addition of links

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/760>
This commit is contained in:
Mathieu Duponchelle 2021-02-17 18:35:33 +01:00
parent d7e2861398
commit 670596abdb
2 changed files with 25 additions and 10 deletions

View file

@ -34,6 +34,17 @@
* caps (simple caps = one line) * 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 "gst_private.h"
#include "gstdebugutils.h" #include "gstdebugutils.h"
@ -799,7 +810,7 @@ debug_dump_footer (GString * str)
* @details: type of #GstDebugGraphDetails to use * @details: type of #GstDebugGraphDetails to use
* *
* To aid debugging applications one can use this method to obtain the whole * 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. * This data can be processed with graphviz to get an image.
* *
* Returns: (transfer full): a string containing the pipeline in graphviz * 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") * @file_name: (type filename): output base filename (e.g. "myplayer")
* *
* To aid debugging applications one can use this method to write out the whole * 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. * This file can be processed with graphviz to get an image.
* *
* ``` shell * ``` shell

View file

@ -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") * @file_name: output base filename (e.g. "myplayer")
* *
* To aid debugging applications one can use this method to write out the whole * 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: * This file can be processed with graphviz to get an image, like this:
* |[ *
* dot -Tpng -oimage.png graph_lowlevel.dot * ``` shell
* ]| * dot -Tpng -oimage.png graph_lowlevel.dot
* There is also a utility called xdot which allows you to view the dot file * ```
*
* There is also a utility called [xdot] which allows you to view the dot file
* directly without converting it first. * directly without converting it first.
* *
* The macro is only active if the environment variable GST_DEBUG_DUMP_DOT_DIR * 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 * is set to a basepath (e.g. `/tmp`), and the GStreamer debugging subsystem is
* enabled (i.e., no use of `./configure --disable-gst-debug') * 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) #define GST_DEBUG_BIN_TO_DOT_FILE(bin, details, file_name) gst_debug_bin_to_dot_file (bin, details, file_name)