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

102
main/pbx_app.c
View File

@@ -46,6 +46,7 @@ struct ast_app {
int (*execute)(struct ast_channel *chan, const char *data);
AST_DECLARE_STRING_FIELDS(
AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show applications' */
AST_STRING_FIELD(since); /*!< Since text for 'show applications' */
AST_STRING_FIELD(description); /*!< Description (help text) for 'show application &lt;name&gt;' */
AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show applications' */
AST_STRING_FIELD(arguments); /*!< Arguments description */
@@ -142,6 +143,11 @@ int ast_register_application2(const char *app, int (*execute)(struct ast_channel
ast_string_field_set(tmp, synopsis, tmpxml);
ast_free(tmpxml);
/* load since */
tmpxml = ast_xmldoc_build_since("application", app, ast_module_name(tmp->module));
ast_string_field_set(tmp, since, tmpxml);
ast_free(tmpxml);
/* load description */
tmpxml = ast_xmldoc_build_description("application", app, ast_module_name(tmp->module));
ast_string_field_set(tmp, description, tmpxml);
@@ -191,67 +197,61 @@ int ast_register_application2(const char *app, int (*execute)(struct ast_channel
static void print_app_docs(struct ast_app *aa, int fd)
{
char *synopsis = NULL, *since = NULL, *description = NULL, *syntax = NULL, *arguments = NULL, *seealso = NULL;
#ifdef AST_XML_DOCS
char *synopsis = NULL, *description = NULL, *arguments = NULL, *seealso = NULL;
if (aa->docsrc == AST_XML_DOC) {
synopsis = ast_xmldoc_printable(S_OR(aa->synopsis, "Not available"), 1);
since = ast_xmldoc_printable(S_OR(aa->since, "Not available"), 1);
description = ast_xmldoc_printable(S_OR(aa->description, "Not available"), 1);
syntax = ast_xmldoc_printable(S_OR(aa->syntax, "Not available"), 1);
arguments = ast_xmldoc_printable(S_OR(aa->arguments, "Not available"), 1);
seealso = ast_xmldoc_printable(S_OR(aa->seealso, "Not available"), 1);
if (!synopsis || !description || !arguments || !seealso) {
goto free_docs;
}
ast_cli(fd, "\n"
"%s -= Info about application '%s' =- %s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s%s%s\n\n"
COLORIZE_FMT "\n"
"%s\n\n"
COLORIZE_FMT "\n"
"%s\n",
ast_term_color(COLOR_MAGENTA, 0), aa->name, ast_term_reset(),
COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"), synopsis,
COLORIZE(COLOR_MAGENTA, 0, "[Description]"), description,
COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"),
ast_term_color(COLOR_CYAN, 0), S_OR(aa->syntax, "Not available"), ast_term_reset(),
COLORIZE(COLOR_MAGENTA, 0, "[Arguments]"), arguments,
COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso);
free_docs:
ast_free(synopsis);
ast_free(description);
ast_free(arguments);
ast_free(seealso);
} else
#endif
{
ast_cli(fd, "\n"
"%s -= Info about application '%s' =- %s\n\n"
COLORIZE_FMT "\n"
COLORIZE_FMT "\n\n"
COLORIZE_FMT "\n"
COLORIZE_FMT "\n\n"
COLORIZE_FMT "\n"
COLORIZE_FMT "\n\n"
COLORIZE_FMT "\n"
COLORIZE_FMT "\n\n"
COLORIZE_FMT "\n"
COLORIZE_FMT "\n",
ast_term_color(COLOR_MAGENTA, 0), aa->name, ast_term_reset(),
COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"),
COLORIZE(COLOR_CYAN, 0, S_OR(aa->synopsis, "Not available")),
COLORIZE(COLOR_MAGENTA, 0, "[Description]"),
COLORIZE(COLOR_CYAN, 0, S_OR(aa->description, "Not available")),
COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"),
COLORIZE(COLOR_CYAN, 0, S_OR(aa->syntax, "Not available")),
COLORIZE(COLOR_MAGENTA, 0, "[Arguments]"),
COLORIZE(COLOR_CYAN, 0, S_OR(aa->arguments, "Not available")),
COLORIZE(COLOR_MAGENTA, 0, "[See Also]"),
COLORIZE(COLOR_CYAN, 0, S_OR(aa->seealso, "Not available")));
synopsis = ast_strdup(S_OR(aa->synopsis, "Not Available"));
since = ast_strdup(S_OR(aa->since, "Not Available"));
description = ast_strdup(S_OR(aa->description, "Not Available"));
syntax = ast_strdup(S_OR(aa->syntax, "Not Available"));
arguments = ast_strdup(S_OR(aa->arguments, "Not Available"));
seealso = ast_strdup(S_OR(aa->seealso, "Not Available"));
}
/* check allocated memory. */
if (!synopsis || !since || !description || !syntax || !arguments || !seealso) {
goto free_docs;
}
ast_cli(fd, "\n"
"%s -= Info about Application '%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"
COLORIZE_FMT "\n"
"%s\n\n",
ast_term_color(COLOR_MAGENTA, 0), aa->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, "[Arguments]"), arguments,
COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso
);
free_docs:
ast_free(synopsis);
ast_free(since);
ast_free(description);
ast_free(syntax);
ast_free(arguments);
ast_free(seealso);
}
/*!