kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-10-02 02:18:31 +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.
This commit is contained in:
George Joseph
2025-01-09 15:17:14 -07:00
parent 4c8c37b21b
commit c010fd4689
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);
}
/*!