mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-03 11:11:05 +00:00
docs: Enable since/version handling for XML, CLI and ARI documentation
* Added the "since" element to the XML configObject and configOption elements
in appdocsxml.dtd.
* Added the "Since" section to the following CLI output:
```
config show help <module> <object>
config show help <module> <object> <option>
core show application <app>
core show function <func>
manager show command <command>
manager show event <event>
agi show commands topic <topic>
```
* Refactored the commands above to output their sections in the same order:
Synopsis, Since, Description, Syntax, Arguments, SeeAlso
* Refactored the commands above so they all use the same pattern for writing
the output to the CLI.
* Fixed several memory leaks caused by failure to free temporary output
buffers.
* Added a "since" array to the mustache template for the top-level resources
(Channel, Endpoint, etc.) and to the paths/methods underneath them. These
will be added to the generated markdown if present.
Example:
```
"resourcePath": "/api-docs/channels.{format}",
"requiresModules": [
"res_stasis_answer",
"res_stasis_playback",
"res_stasis_recording",
"res_stasis_snoop"
],
"since": [
"18.0.0",
"21.0.0"
],
"apis": [
{
"path": "/channels",
"description": "Active channels",
"operations": [
{
"httpMethod": "GET",
"since": [
"18.6.0",
"21.8.0"
],
"summary": "List all active channels in Asterisk.",
"nickname": "list",
"responseClass": "List[Channel]"
},
```
NOTE: No versioning information is actually added in this commit.
Those will be added separately and instructions for adding and maintaining
them will be published on the documentation site at a later date.
(cherry picked from commit 3e28ddce78
)
This commit is contained in:
committed by
Asterisk Development Team
parent
d468918359
commit
24c077f1fb
@@ -60,6 +60,10 @@ typedef struct agi_command {
|
||||
struct ast_module *mod;
|
||||
/*! Linked list pointer */
|
||||
AST_LIST_ENTRY(agi_command) list;
|
||||
/*! Since content */
|
||||
const char * const since;
|
||||
/*! Syntax arguments content */
|
||||
const char * const arguments;
|
||||
} agi_command;
|
||||
|
||||
/*!
|
||||
|
@@ -181,6 +181,7 @@ struct manager_action {
|
||||
* function and unregistering the AMI action object.
|
||||
*/
|
||||
unsigned int registered:1;
|
||||
AST_STRING_FIELD_EXTENDED(since); /*!< Documentation "since" element */
|
||||
};
|
||||
|
||||
/*! \brief External routines may register/unregister manager callbacks this way
|
||||
|
@@ -150,6 +150,7 @@ struct ast_custom_function {
|
||||
* \since 12 */
|
||||
|
||||
AST_RWLIST_ENTRY(ast_custom_function) acflist;
|
||||
AST_STRING_FIELD_EXTENDED(since); /*!< Since text for 'show functions' */
|
||||
};
|
||||
|
||||
/*! \brief All switch functions have the same interface, so define a type for them */
|
||||
|
@@ -78,6 +78,8 @@ struct ast_xml_doc_item {
|
||||
struct ast_xml_node *node;
|
||||
/*! The next XML documentation item that matches the same name/item type */
|
||||
AST_LIST_ENTRY(ast_xml_doc_item) next;
|
||||
/*! Since tagged information, if it exists */
|
||||
struct ast_str *since;
|
||||
};
|
||||
|
||||
/*! \brief Execute an XPath query on the loaded XML documentation
|
||||
@@ -110,6 +112,16 @@ char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *mo
|
||||
*/
|
||||
char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module);
|
||||
|
||||
/*!
|
||||
* \brief Parse the <since> node content.
|
||||
* \param type 'application', 'function' or 'agi'.
|
||||
* \param name Application or functions name.
|
||||
* \param module The module the item is in (optional, can be NULL)
|
||||
* \retval NULL on error.
|
||||
* \retval Content of the since node.
|
||||
*/
|
||||
char *ast_xmldoc_build_since(const char *type, const char *name, const char *module);
|
||||
|
||||
/*!
|
||||
* \brief Generate the [arguments] tag based on type of node ('application',
|
||||
* 'function' or 'agi') and name.
|
||||
|
Reference in New Issue
Block a user