Review Board 1.7.16


xmldoc: Add support for an <example> tag in the Asterisk XML documentation

Review Request #3807 - Created July 16, 2014 and submitted

Matt Jordan
trunk
Reviewers
asterisk-dev
Asterisk
This patch adds support for an <example /> tag in the XML documentation schema.

For CLI help, this doesn't change the formatting too much:
 - Preceeding white space is removed
 - Unlike with para elements, new lines are preserved

However, having an <example /> tag in the XML schema allows for the wiki documentation generation script to surround the documentation with {code} or {noformat} tags, generating much better content for the wiki - and allowing us to put dialplan examples (and other code snippets, if desired) into the documentation for an application/function/AMI command/etc.
Updated the JITTERBUFFER function. It now displays its dialplan examples in a single example block in the CLI help.

Diff revision 4 (Latest)

1 2 3 4
1 2 3 4

  1. /trunk/doc/appdocsxml.dtd: Loading...
  2. /trunk/funcs/func_jitterbuffer.c: Loading...
  3. /trunk/main/xmldoc.c: Loading...
/trunk/doc/appdocsxml.dtd
Revision 419680 New Change
[20] 89 lines
[+20]
90
  <!ATTLIST bridge_snapshot prefix CDATA "">
90
  <!ATTLIST bridge_snapshot prefix CDATA "">
91

    
   
91

   
92
  <!ELEMENT configOptionToEnum (configOption|xi:include)*>
92
  <!ELEMENT configOptionToEnum (configOption|xi:include)*>
93
  <!ATTLIST configOptionToEnum prefix CDATA "">
93
  <!ATTLIST configOptionToEnum prefix CDATA "">
94

    
   
94

   
95
  <!ELEMENT description (para|note|warning|variablelist|enumlist|info|xi:include)*>
95
  <!ELEMENT description (para|note|warning|variablelist|enumlist|info|example|xi:include)*>
96

    
   
96

   
97
  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
97
  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
98
  <!ATTLIST parameter name CDATA "">
98
  <!ATTLIST parameter name CDATA "">
99
  <!ATTLIST parameter required (yes|no|true|false) "false">
99
  <!ATTLIST parameter required (yes|no|true|false) "false">
100
  <!ATTLIST parameter multiple (yes|no|true|false) "false">
100
  <!ATTLIST parameter multiple (yes|no|true|false) "false">
[+20] [20] 26 lines
[+20]
127
  <!ELEMENT filename (#PCDATA)>
127
  <!ELEMENT filename (#PCDATA)>
128
  <!ELEMENT replaceable (#PCDATA)>
128
  <!ELEMENT replaceable (#PCDATA)>
129
  <!ELEMENT directory (#PCDATA)>
129
  <!ELEMENT directory (#PCDATA)>
130
  <!ELEMENT astcli (#PCDATA)>
130
  <!ELEMENT astcli (#PCDATA)>
131

    
   
131

   

    
   
132
  <!ELEMENT example (#PCDATA|xi:include)*>

    
   
133
  <!ATTLIST example title CDATA "">

    
   
134
  <!ATTLIST example language CDATA "" >

    
   
135

   
132
  <!ELEMENT note (para+|xi:include*)>
136
  <!ELEMENT note (para+|xi:include*)>
133
  <!ELEMENT warning (para+|xi:include*)>
137
  <!ELEMENT warning (para+|xi:include*)>
134

    
   
138

   
135
  <!ELEMENT variablelist (variable+|xi:include*)>
139
  <!ELEMENT variablelist (variable+|xi:include*)>
136
  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
140
  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
137
  <!ATTLIST variable name CDATA "">
141
  <!ATTLIST variable name CDATA "">
138

    
   
142

   
139
  <!ELEMENT value (#PCDATA)>
143
  <!ELEMENT value (#PCDATA)>
140
  <!ATTLIST value name CDATA #REQUIRED>
144
  <!ATTLIST value name CDATA #REQUIRED>
141
  <!ATTLIST value default CDATA "">
145
  <!ATTLIST value default CDATA "">
/trunk/funcs/func_jitterbuffer.c
Revision 419680 New Change
 
/trunk/main/xmldoc.c
Revision 419680 New Change
 
  1. /trunk/doc/appdocsxml.dtd: Loading...
  2. /trunk/funcs/func_jitterbuffer.c: Loading...
  3. /trunk/main/xmldoc.c: Loading...

https://reviewboard.asterisk.org/ runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to asteriskteam@digium.com.