[Asterisk-code-review] progdocs: Use Doxygen \example correctly. (asterisk[master])

[George Joseph]

George Joseph has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17338 )

Change subject: progdocs: Use Doxygen \example correctly.
......................................................................

progdocs: Use Doxygen \example correctly.

ASTERISK-29734

Change-Id: I83b51e85cd71867645ab3a8a820f8fd1f065abd2
---
M include/asterisk/logger.h
M include/asterisk/strings.h
M main/app.c
3 files changed, 14 insertions(+), 9 deletions(-)

Approvals:
  Kevin Harwell: Looks good to me, but someone else must approve
  George Joseph: Looks good to me, approved; Approved for Submit



diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index c1b023f..08e90bb 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -822,7 +822,7 @@
  * \details
  * Handy for getting out of or continuing loops.
  *
- * \example
+ * \code
  * while(something) {
  *     SCOPE_ENTER(2, "In a while\n");
  *     if (something) {
@@ -831,6 +831,7 @@
  *         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 9ca3234..59dece8 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -1117,30 +1117,35 @@
  * \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 411d507..68a51dc 100644
--- a/main/app.c
+++ b/main/app.c
@@ -23,10 +23,9 @@
  * \author Mark Spencer <markster at 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

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17338
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: I83b51e85cd71867645ab3a8a820f8fd1f065abd2
Gerrit-Change-Number: 17338
Gerrit-PatchSet: 2
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211118/1f65e999/attachment.html>