From 1d05e34d98f3958aae64bd125ed1039f95f65125 Mon Sep 17 00:00:00 2001
From: Sean Bright <sean@seanbright.com>
Date: Fri, 1 Dec 2023 12:03:29 -0500
Subject: [PATCH] logger.c: Move LOG_GROUP documentation to dedicated XML file.
The `get_documentation` awk script will only extract the first
DOCUMENTATION block that it finds in a given file. This is by design
(9bc2127) to prevent AMI event documentation from being pulled in to
the core.xml documentation file.
Because of this, the `LOG_GROUP` documentation added in 89709e2 was
not being properly extracted and was missing fom the resulting XML
documentation file. This commit moves the `LOG_GROUP` documentation to
a separate `logger.xml` file.
---
main/logger.c | 35 -----------------------------------
main/logger.xml | 37 +++++++++++++++++++++++++++++++++++++
2 files changed, 37 insertions(+), 35 deletions(-)
create mode 100644 main/logger.xml
diff --git a/main/logger.c b/main/logger.c
index 60f464c8a8..c460e91cf4 100644
--- a/main/logger.c
+++ b/main/logger.c
@@ -1776,41 +1776,6 @@ static int callid_logging_enabled(void)
return cgl ? 1 : 0; /* If found, enabled, otherwise not */
}
-/*** DOCUMENTATION
- <function name="LOG_GROUP" language="en_US">
- <synopsis>
- Set the channel group name for log filtering on this channel
- </synopsis>
- <syntax>
- <parameter name="group" required="false">
- <para>Channel log group name. Leave empty to remove any existing group membership.</para>
- <para>You can use any arbitrary alphanumeric name that can then be used by the
- "logger filter changroup" CLI command to filter dialplan output by group name.</para>
- </parameter>
- </syntax>
- <description>
- <para>Assign a channel to a group for log filtering.</para>
- <para>Because this application can result in dialplan execution logs
- being suppressed (or unsuppressed) from the CLI if filtering is active,
- it is recommended to call this as soon as possible when dialplan execution begins.</para>
- <para>Calling this multiple times will replace any previous group assignment.</para>
- <example title="Associate channel with group test">
- exten => s,1,Set(LOG_GROUP()=test)
- same => n,NoOp() ; if a logging call ID group filter name is enabled but test is not included, you will not see this
- </example>
- <example title="Associate channel with group important">
- exten => s,1,Set(LOG_GROUP()=important)
- same => n,Set(foo=bar) ; do some important things to show on the CLI (assuming it is filtered with important enabled)
- same => n,Set(LOG_GROUP()=) ; remove from group important to stop showing execution on the CLI
- same => n,Wait(5) ; do some unimportant stuff
- </example>
- </description>
- <see-also>
- <ref type="application">Log</ref>
- </see-also>
- </function>
- ***/
-
static int log_group_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
{
int res = callid_set_chanloggroup(value);
diff --git a/main/logger.xml b/main/logger.xml
new file mode 100644
index 0000000000..fa4ddff4ba
--- /dev/null
+++ b/main/logger.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE docs SYSTEM "appdocsxml.dtd">
+<?xml-stylesheet type="text/xsl" href="appdocsxml.xslt"?>
+<docs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <function name="LOG_GROUP" language="en_US">
+ <synopsis>
+ Set the channel group name for log filtering on this channel
+ </synopsis>
+ <syntax>
+ <parameter name="group" required="false">
+ <para>Channel log group name. Leave empty to remove any existing group membership.</para>
+ <para>You can use any arbitrary alphanumeric name that can then be used by the
+ "logger filter changroup" CLI command to filter dialplan output by group name.</para>
+ </parameter>
+ </syntax>
+ <description>
+ <para>Assign a channel to a group for log filtering.</para>
+ <para>Because this application can result in dialplan execution logs
+ being suppressed (or unsuppressed) from the CLI if filtering is active,
+ it is recommended to call this as soon as possible when dialplan execution begins.</para>
+ <para>Calling this multiple times will replace any previous group assignment.</para>
+ <example title="Associate channel with group test">
+ exten => s,1,Set(LOG_GROUP()=test)
+ same => n,NoOp() ; if a logging call ID group filter name is enabled but test is not included, you will not see this
+ </example>
+ <example title="Associate channel with group important">
+ exten => s,1,Set(LOG_GROUP()=important)
+ same => n,Set(foo=bar) ; do some important things to show on the CLI (assuming it is filtered with important enabled)
+ same => n,Set(LOG_GROUP()=) ; remove from group important to stop showing execution on the CLI
+ same => n,Wait(5) ; do some unimportant stuff
+ </example>
+ </description>
+ <see-also>
+ <ref type="application">Log</ref>
+ </see-also>
+ </function>
+</docs>