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.
This commit is contained in:
George Joseph
2025-01-09 15:17:14 -07:00
parent ae106fadfe
commit 3868f7cb47
13 changed files with 493 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/appdocsxml.dtd
View File

@@ -72,10 +72,10 @@
<!ELEMENT configFile (configObject|xi:include)+>
<!ATTLIST configFile name CDATA #REQUIRED>
<!ELEMENT configObject (synopsis?|description?|syntax?|see-also?|(configOption|xi:include))*>
<!ELEMENT configObject (since?|synopsis?|description?|syntax?|see-also?|(configOption|xi:include))*>
<!ATTLIST configObject name CDATA #REQUIRED>
<!ELEMENT configOption (synopsis,description?,syntax?,see-also?)*>
<!ELEMENT configOption (since?,synopsis,description?,syntax?,see-also?)*>
<!ATTLIST configOption name CDATA #REQUIRED>
<!ATTLIST configOption regex (yes|no|true|false) "false">
<!ATTLIST configOption default CDATA #IMPLIED>