]> 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:35 +0000 (14:20 +0000)
commit3c867e6e6c2c76600b82805f1bb8d54d1398a01f
treea341fe9653722cc87439e8da83abbca2a07a63a3
parent92d69897b7251bcd5d79467c333104eeb10f8a1c
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