kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-02 19:16:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Enable since/version handling for XML, CLI and ARI documentation

Browse Source 
* 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:
George Joseph
2025-01-09 15:17:14 -07:00
committed by Asterisk Development Team
parent d468918359
commit 24c077f1fb
13 changed files with 493 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
main/config_options.c
View File

@@ -1244,10 +1244,14 @@ static void cli_show_module_types(struct ast_cli_args *a)
}
if (ast_str_strlen(item->synopsis)) {
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(item->synopsis), 1));
char *value = ast_xmldoc_printable(ast_str_buffer(item->synopsis), 1);
ast_cli(a->fd, "%s\n\n", value);
ast_free(value);
}
if (ast_str_strlen(item->description)) {
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(item->description), 1));
char *value = ast_xmldoc_printable(ast_str_buffer(item->description), 1);
ast_cli(a->fd, "%s\n\n",value);
ast_free(value);
}
tmp = item;
@@ -1267,8 +1271,8 @@ static void cli_show_module_type(struct ast_cli_args *a)
{
RAII_VAR(struct ast_xml_doc_item *, item, NULL, ao2_cleanup);
struct ast_xml_doc_item *tmp;
char option_type[64];
int match = 0;
char *synopsis, *since, *description, *syntax, *seealso;
ast_assert(a->argc == 5);
@@ -1281,19 +1285,48 @@ static void cli_show_module_type(struct ast_cli_args *a)
while ((tmp = AST_LIST_NEXT(tmp, next))) {
if (!strcasecmp(tmp->type, "configObject") && !strcasecmp(tmp->name, a->argv[4])) {
match = 1;
term_color(option_type, tmp->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(option_type));
ast_cli(a->fd, "%s", option_type);
if (ast_str_strlen(tmp->syntax)) {
ast_cli(a->fd, ": [%s]\n\n", ast_xmldoc_printable(ast_str_buffer(tmp->syntax), 1));
} else {
ast_cli(a->fd, "\n\n");
}
if (ast_str_strlen(tmp->synopsis)) {
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(tmp->synopsis), 1));
}
if (ast_str_strlen(tmp->description)) {
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(tmp->description), 1));
synopsis = ast_xmldoc_printable(AS_OR(tmp->synopsis, "Not available"), 1);
since = ast_xmldoc_printable(AS_OR(tmp->since, "Not available"), 1);
description = ast_xmldoc_printable(AS_OR(tmp->description, "Not available"), 1);
syntax = ast_xmldoc_printable(AS_OR(tmp->syntax, "Not available"), 1);
seealso = ast_xmldoc_printable(AS_OR(tmp->seealso, "Not available"), 1);
if (!synopsis || !since || !description || !syntax || !seealso ) {
ast_free(synopsis);
ast_free(since);
ast_free(description);
ast_free(syntax);
ast_free(seealso);
ast_cli(a->fd, "Error: Memory allocation failed\n");
break;
}
ast_cli(a->fd, "\n"
"%s -= Info about Config Object '%s:%s' =- %s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s [%s]\n\n"
COLORIZE_FMT "\n"
"%s\n\n",
ast_term_color(COLOR_MAGENTA, 0), a->argv[3], tmp->name, ast_term_reset(),
COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"), synopsis,
COLORIZE(COLOR_MAGENTA, 0, "[Since]"), since,
COLORIZE(COLOR_MAGENTA, 0, "[Description]"), description,
COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"), tmp->name, syntax,
COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso
);
ast_free(synopsis);
ast_free(since);
ast_free(description);
ast_free(syntax);
ast_free(seealso);
}
}
@@ -1304,6 +1337,8 @@ static void cli_show_module_type(struct ast_cli_args *a)
/* Now iterate over the options for the type */
tmp = item;
ast_cli(a->fd, COLORIZE_FMT "\n", COLORIZE(COLOR_MAGENTA, 0, "[Config Options]"));
while ((tmp = AST_LIST_NEXT(tmp, next))) {
if (!strcasecmp(tmp->type, "configOption") && !strcasecmp(tmp->ref, a->argv[4])) {
ast_cli(a->fd, "%-25s -- %-120.120s\n", tmp->name,
@@ -1319,8 +1354,8 @@ static void cli_show_module_options(struct ast_cli_args *a)
{
RAII_VAR(struct ast_xml_doc_item *, item, NULL, ao2_cleanup);
struct ast_xml_doc_item *tmp;
char option_name[64];
int match = 0;
char *synopsis, *since, *description, *syntax, *seealso;
ast_assert(a->argc == 6);
@@ -1334,20 +1369,47 @@ static void cli_show_module_options(struct ast_cli_args *a)
if (match) {
ast_cli(a->fd, "\n");
}
term_color(option_name, tmp->ref, COLOR_MAGENTA, COLOR_BLACK, sizeof(option_name));
ast_cli(a->fd, "[%s%s]\n", option_name, ast_term_reset());
if (ast_str_strlen(tmp->syntax)) {
ast_cli(a->fd, "%s\n", ast_xmldoc_printable(ast_str_buffer(tmp->syntax), 1));
}
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(AS_OR(tmp->synopsis, "No information available"), 1));
if (ast_str_strlen(tmp->description)) {
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(tmp->description), 1));
synopsis = ast_xmldoc_printable(AS_OR(tmp->synopsis, "Not available"), 1);
since = ast_xmldoc_printable(AS_OR(tmp->since, "Not available"), 1);
description = ast_xmldoc_printable(AS_OR(tmp->description, "Not available"), 1);
syntax = ast_xmldoc_printable(AS_OR(tmp->syntax, "Not available"), 1);
seealso = ast_xmldoc_printable(AS_OR(tmp->seealso, "Not available"), 1);
if (!synopsis || !since || !description || !syntax || !seealso ) {
ast_free(synopsis);
ast_free(since);
ast_free(description);
ast_free(syntax);
ast_free(seealso);
ast_cli(a->fd, "Error: Memory allocation failed\n");
break;
}
if (ast_str_strlen(tmp->seealso)) {
ast_cli(a->fd, "See Also:\n");
ast_cli(a->fd, "%s\n\n", ast_xmldoc_printable(ast_str_buffer(tmp->seealso), 1));
}
ast_cli(a->fd, "\n"
"%s -= Info about Config Option '%s:%s:%s' =- %s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n",
ast_term_color(COLOR_MAGENTA, 0), a->argv[3], a->argv[4], tmp->name, ast_term_reset(),
COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"), synopsis,
COLORIZE(COLOR_MAGENTA, 0, "[Since]"), since,
COLORIZE(COLOR_MAGENTA, 0, "[Description]"), description,
COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"), syntax,
COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso
);
ast_free(synopsis);
ast_free(since);
ast_free(description);
ast_free(syntax);
ast_free(seealso);
match = 1;
}