mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-04 03:50:31 +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.
This commit is contained in:
@@ -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