From 23b16c5372b7de7d38ae3c21597468f85827fc1e Mon Sep 17 00:00:00 2001
From: Alexander Traud <pabstraud@compuserve.com>
Date: Fri, 12 Nov 2021 20:17:20 +0100
Subject: [PATCH] progdocs: Use Doxygen \example correctly.
ASTERISK-29734
Change-Id: I83b51e85cd71867645ab3a8a820f8fd1f065abd2
---
include/asterisk/logger.h | 3 ++-
include/asterisk/strings.h | 15 ++++++++++-----
main/app.c | 5 ++---
3 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index 170fb68fd7..76d63671be 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -821,7 +821,7 @@ unsigned long _ast_trace_dec_indent(void);
* \details
* Handy for getting out of or continuing loops.
*
- * \example
+ * \code
* while(something) {
* SCOPE_ENTER(2, "In a while\n");
* if (something) {
@@ -830,6 +830,7 @@ unsigned long _ast_trace_dec_indent(void);
* SCOPE_EXIT_EXPR(continue, "Somethiung continued me\n");
* }
* }
+ * \endcode
*/
#define SCOPE_EXIT_EXPR(__expr, ...) \
ast_debug(__scope_level, " " __VA_ARGS__); \
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 9ca3234d10..59dece88b2 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -1117,30 +1117,35 @@ int __attribute__((format(printf, 3, 4))) ast_str_append(
* \details
* There are a few query functions scattered around that need an ast_str in which
* to assemble the results but it's not always convenient to create an ast_str
- * and ensure it's freed just to print a log message. For example...
+ * and ensure it's freed just to print a log message. For example:
*
+ * \code
* struct ast_str *temp = ast_str_create(128);
* ast_log(LOG_INFO, "Format caps: %s\n", ast_format_cap_get_names(caps, &temp));
* ast_free(temp);
+ * \endcode
*
* That's not bad if you only have to do it once but some of our code that deals
* with streams and codecs is pretty complex and good instrumentation is essential.
* The aim of this function is to make that easier.
*
- * With this macro, the above code can be simplified as follows...
- * \example
+ * With this macro, the above code can be simplified:
+ *
+ * \code
* ast_log(LOG_INFO, "Format caps: %s\n",
* ast_str_tmp(128, ast_format_cap_get_names(caps, &STR_TMP));
+ * \endcode
*
* STR_TMP will always be a reference to the temporary ast_str created
* by the macro. Its scope is limited by the macro so you can use it multiple
- * times without conflict.
+ * times without conflict:
*
- * \example
+ * \code
* ast_log(LOG_INFO, "Format caps in: %s Format caps out: %s\n",
* ast_str_tmp(128, ast_format_cap_get_names(caps_in, &STR_TMP),
* ast_str_tmp(128, ast_format_cap_get_names(caps_out, &STR_TMP)
* );
+ * \endcode
*
* \warning
* The returned string is stack allocated so don't go overboard.
diff --git a/main/app.c b/main/app.c
index 411d5077b0..68a51dc2f1 100644
--- a/main/app.c
+++ b/main/app.c
@@ -23,10 +23,9 @@
* \author Mark Spencer <markster@digium.com>
*/
-/** \example
- * \par This is an example of how to develop an app.
+/*!
* Application Skeleton is an example of creating an application for Asterisk.
- * \verbinclude app_skel.c
+ * \example app_skel.c
*/
/*** MODULEINFO
--
GitLab