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>

2 files changed, 25 insertions, 10 deletions

diff --git a/gst/gstdebugutils.c b/gst/gstdebugutils.c
index e501c61d0e..8ca334afba 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 3808fc6bdf..6a2caa94a8 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)