kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-10-31 02:37:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
26ad51c2ffa813180ed309ac3f7c8d3db9ccaf74
asterisk/main/logger_doc.xml

71 lines
2.7 KiB
XML
Raw Normal View History

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.
2023-12-01 12:03:29 -05:00
<?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">
docs: Indent <since> tags. Also updates the 'since' of applications/functions that existed before XML documentation was introduced (1.6.2.0). (cherry picked from commit 67e89b3e77b56186b334e546ddb389579c20f3b1)
2025-01-23 16:35:58 -05:00
<since>
<version>18.21.0</version>
<version>20.6.0</version>
<version>21.1.0</version>
</since>
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.
2023-12-01 12:03:29 -05:00
<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: Add version information to manager event instance XML elements * Do a git blame on the embedded XML managerEvent elements. * From the commit hash, grab the summary line. * Do a git log --grep <summary> to find the cherry-pick commits in all branches that match. * Do a git patch-id to ensure the commits are all related and didn't get a false match on the summary. * Do a git tag --contains <commit> to find the tags that contain each commit. * Weed out all tags not ..0. * Sort and discard any .0.0 and following tags where the commit appeared in an earlier branch. * The result is a single tag for each branch where the application or function was defined. The events defined in res/res_pjsip/pjsip_manager.xml were done by hand because the XML was extracted from the C source file relatively recently. Two bugs were fixed along the way... * The get_documentation awk script was exiting after it processed the first DOCUMENTATION block it found in a file. We have at least 1 source file with multiple DOCUMENTATION blocks so only the first one in them was being processed. The awk script was changed to continue searching rather than exiting after the first block. * Fixing the awk script revealed an issue in logger.c where the third DOCUMENTATION block contained a XML fragment that consisted only of a managerEventInstance element that wasn't wrapped in a managerEvent element. Since logger_doc.xml already existed, the remaining fragments in logger.c were moved to it and properly organized. (cherry picked from commit 936e88512e41c7fd5db5fb1628759ae591b50be2)
2025-01-20 11:33:20 -07:00
<managerEvent language="en_US" name="LogChannel">
<managerEventInstance class="EVENT_FLAG_SYSTEM">
docs: Indent <since> tags. Also updates the 'since' of applications/functions that existed before XML documentation was introduced (1.6.2.0). (cherry picked from commit 67e89b3e77b56186b334e546ddb389579c20f3b1)
2025-01-23 16:35:58 -05:00
<since>
<version>16.24.0</version>
<version>18.10.0</version>
<version>19.2.0</version>
</since>
docs: Add version information to manager event instance XML elements * Do a git blame on the embedded XML managerEvent elements. * From the commit hash, grab the summary line. * Do a git log --grep <summary> to find the cherry-pick commits in all branches that match. * Do a git patch-id to ensure the commits are all related and didn't get a false match on the summary. * Do a git tag --contains <commit> to find the tags that contain each commit. * Weed out all tags not ..0. * Sort and discard any .0.0 and following tags where the commit appeared in an earlier branch. * The result is a single tag for each branch where the application or function was defined. The events defined in res/res_pjsip/pjsip_manager.xml were done by hand because the XML was extracted from the C source file relatively recently. Two bugs were fixed along the way... * The get_documentation awk script was exiting after it processed the first DOCUMENTATION block it found in a file. We have at least 1 source file with multiple DOCUMENTATION blocks so only the first one in them was being processed. The awk script was changed to continue searching rather than exiting after the first block. * Fixing the awk script revealed an issue in logger.c where the third DOCUMENTATION block contained a XML fragment that consisted only of a managerEventInstance element that wasn't wrapped in a managerEvent element. Since logger_doc.xml already existed, the remaining fragments in logger.c were moved to it and properly organized. (cherry picked from commit 936e88512e41c7fd5db5fb1628759ae591b50be2)
2025-01-20 11:33:20 -07:00
<synopsis>Raised when a logging channel is re-enabled after a reload operation.</synopsis>
<syntax>
<parameter name="Channel">
<para>The name of the logging channel.</para>
</parameter>
</syntax>
</managerEventInstance>
<managerEventInstance class="EVENT_FLAG_SYSTEM">
docs: Indent <since> tags. Also updates the 'since' of applications/functions that existed before XML documentation was introduced (1.6.2.0). (cherry picked from commit 67e89b3e77b56186b334e546ddb389579c20f3b1)
2025-01-23 16:35:58 -05:00
<since>
<version>16.24.0</version>
<version>18.10.0</version>
<version>19.2.0</version>
</since>
docs: Add version information to manager event instance XML elements * Do a git blame on the embedded XML managerEvent elements. * From the commit hash, grab the summary line. * Do a git log --grep <summary> to find the cherry-pick commits in all branches that match. * Do a git patch-id to ensure the commits are all related and didn't get a false match on the summary. * Do a git tag --contains <commit> to find the tags that contain each commit. * Weed out all tags not ..0. * Sort and discard any .0.0 and following tags where the commit appeared in an earlier branch. * The result is a single tag for each branch where the application or function was defined. The events defined in res/res_pjsip/pjsip_manager.xml were done by hand because the XML was extracted from the C source file relatively recently. Two bugs were fixed along the way... * The get_documentation awk script was exiting after it processed the first DOCUMENTATION block it found in a file. We have at least 1 source file with multiple DOCUMENTATION blocks so only the first one in them was being processed. The awk script was changed to continue searching rather than exiting after the first block. * Fixing the awk script revealed an issue in logger.c where the third DOCUMENTATION block contained a XML fragment that consisted only of a managerEventInstance element that wasn't wrapped in a managerEvent element. Since logger_doc.xml already existed, the remaining fragments in logger.c were moved to it and properly organized. (cherry picked from commit 936e88512e41c7fd5db5fb1628759ae591b50be2)
2025-01-20 11:33:20 -07:00
<synopsis>Raised when a logging channel is disabled.</synopsis>
<syntax>
<parameter name="Channel">
<para>The name of the logging channel.</para>
</parameter>
</syntax>
</managerEventInstance>
</managerEvent>
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.
2023-12-01 12:03:29 -05:00
</docs>
Reference in New Issue Copy Permalink