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:
George Joseph
2025-01-09 15:17:14 -07:00
parent ae106fadfe
commit 3868f7cb47
13 changed files with 493 additions and 272 deletions

View File

@@ -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;
/*!

View File

@@ -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

View File

@@ -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 */

View File

@@ -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.