]> git.ipfire.org Git - thirdparty/asterisk.git/commit
docs: Enable since/version handling for XML, CLI and ARI documentation
authorGeorge Joseph <gjoseph@sangoma.com>
Thu, 9 Jan 2025 22:17:14 +0000 (15:17 -0700)
committerGeorge Joseph <gjoseph@sangoma.com>
Thu, 16 Jan 2025 14:20:38 +0000 (14:20 +0000)
commitd5e7988df4c0271af64cd8045b0c304ac6ab84c4
treee8de0f4029128b98a6a7f804b86074e9dd90ba5c
parent7d97560656c2408095c237083b7d6abd114fef72
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.
13 files changed:
doc/appdocsxml.dtd
include/asterisk/agi.h
include/asterisk/manager.h
include/asterisk/pbx.h
include/asterisk/xmldoc.h
main/config_options.c
main/manager.c
main/pbx_app.c
main/pbx_functions.c
main/xmldoc.c
res/res_agi.c
rest-api-templates/api.wiki.mustache
rest-api-templates/swagger_model.py