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 1

This is not the most recent revision of the diff. The latest diff is revision 4. See what's changed.

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 418779 New Change
1
  <!ELEMENT docs (application|function|agi|manager|managerEvent|info|configInfo)*>
1
  <!ELEMENT docs (application|function|agi|manager|managerEvent|info|configInfo)*>
2
  <!ATTLIST docs xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">
2
  <!ATTLIST docs xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">
3

    
   
3

   
4
  <!ELEMENT xi:include (xi:fallback?) >
4
  <!ELEMENT xi:include (xi:fallback?) >
5
  <!ATTLIST xi:include
5
  <!ATTLIST xi:include
6
  xmlns:xi	CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
6
  xmlns:xi	CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
7
  href		CDATA       #IMPLIED
7
  href		CDATA       #IMPLIED
8
  parse		(xml|text)  "xml"
8
  parse		(xml|text)  "xml"
9
  xpointer	CDATA       #IMPLIED
9
  xpointer	CDATA       #IMPLIED
10
  encoding	CDATA       #IMPLIED
10
  encoding	CDATA       #IMPLIED
11
  accept	CDATA       #IMPLIED
11
  accept	CDATA       #IMPLIED
12
  accept-language CDATA  #IMPLIED >
12
  accept-language CDATA  #IMPLIED >
13

    
   
13

   
14
  <!ELEMENT application (synopsis?,syntax?,description?,see-also?)>
14
  <!ELEMENT application (synopsis?,syntax?,description?,see-also?)>
15
  <!ATTLIST application name CDATA #REQUIRED>
15
  <!ATTLIST application name CDATA #REQUIRED>
16
  <!ATTLIST application language CDATA #REQUIRED>
16
  <!ATTLIST application language CDATA #REQUIRED>
17
  <!ATTLIST application module CDATA #IMPLIED>
17
  <!ATTLIST application module CDATA #IMPLIED>
18

    
   
18

   
19
  <!ELEMENT function (synopsis?,syntax?,description?,see-also?)>
19
  <!ELEMENT function (synopsis?,syntax?,description?,see-also?)>
20
  <!ATTLIST function name CDATA #REQUIRED>
20
  <!ATTLIST function name CDATA #REQUIRED>
21
  <!ATTLIST function language CDATA #REQUIRED>
21
  <!ATTLIST function language CDATA #REQUIRED>
22
  <!ATTLIST function module CDATA #IMPLIED>
22
  <!ATTLIST function module CDATA #IMPLIED>
23

    
   
23

   
24
  <!ELEMENT agi (synopsis?,syntax?,description?,see-also?)>
24
  <!ELEMENT agi (synopsis?,syntax?,description?,see-also?)>
25
  <!ATTLIST agi name CDATA #REQUIRED>
25
  <!ATTLIST agi name CDATA #REQUIRED>
26
  <!ATTLIST agi language CDATA #REQUIRED>
26
  <!ATTLIST agi language CDATA #REQUIRED>
27
  <!ATTLIST agi module CDATA #IMPLIED>
27
  <!ATTLIST agi module CDATA #IMPLIED>
28

    
   
28

   
29
  <!ELEMENT manager (synopsis?,syntax?,description?,see-also?)>
29
  <!ELEMENT manager (synopsis?,syntax?,description?,see-also?)>
30
  <!ATTLIST manager name CDATA #REQUIRED>
30
  <!ATTLIST manager name CDATA #REQUIRED>
31
  <!ATTLIST manager language CDATA #REQUIRED>
31
  <!ATTLIST manager language CDATA #REQUIRED>
32
  <!ATTLIST manager module CDATA #IMPLIED>
32
  <!ATTLIST manager module CDATA #IMPLIED>
33

    
   
33

   
34
  <!ELEMENT managerEvent (managerEventInstance+)>
34
  <!ELEMENT managerEvent (managerEventInstance+)>
35
  <!ATTLIST managerEvent name CDATA #REQUIRED>
35
  <!ATTLIST managerEvent name CDATA #REQUIRED>
36
  <!ATTLIST managerEvent language CDATA #REQUIRED>
36
  <!ATTLIST managerEvent language CDATA #REQUIRED>
37
  <!ATTLIST managerEvent module CDATA #IMPLIED>
37
  <!ATTLIST managerEvent module CDATA #IMPLIED>
38

    
   
38

   
39
  <!ELEMENT managerEventInstance (synopsis?,syntax?,description?,see-also?)*>
39
  <!ELEMENT managerEventInstance (synopsis?,syntax?,description?,see-also?)*>
40
  <!ATTLIST managerEventInstance class CDATA #REQUIRED>
40
  <!ATTLIST managerEventInstance class CDATA #REQUIRED>
41

    
   
41

   
42
  <!ELEMENT configInfo (synopsis?,description?,configFile+)>
42
  <!ELEMENT configInfo (synopsis?,description?,configFile+)>
43
  <!ATTLIST configInfo name CDATA #REQUIRED>
43
  <!ATTLIST configInfo name CDATA #REQUIRED>
44
  <!ATTLIST configInfo language CDATA #REQUIRED>
44
  <!ATTLIST configInfo language CDATA #REQUIRED>
45

    
   
45

   
46
  <!ELEMENT configFile (configObject+)>
46
  <!ELEMENT configFile (configObject+)>
47
  <!ATTLIST configFile name CDATA #REQUIRED>
47
  <!ATTLIST configFile name CDATA #REQUIRED>
48

    
   
48

   
49
  <!ELEMENT configObject (synopsis?|description?|syntax?|see-also?|configOption)*>
49
  <!ELEMENT configObject (synopsis?|description?|syntax?|see-also?|configOption)*>
50
  <!ATTLIST configObject name CDATA #REQUIRED>
50
  <!ATTLIST configObject name CDATA #REQUIRED>
51

    
   
51

   
52
  <!ELEMENT configOption (synopsis,description?,syntax?,see-also?)*>
52
  <!ELEMENT configOption (synopsis,description?,syntax?,see-also?)*>
53
  <!ATTLIST configOption name CDATA #REQUIRED>
53
  <!ATTLIST configOption name CDATA #REQUIRED>
54
  <!ATTLIST configOption regex (yes|no|true|false) "false">
54
  <!ATTLIST configOption regex (yes|no|true|false) "false">
55
  <!ATTLIST configOption default CDATA #IMPLIED>
55
  <!ATTLIST configOption default CDATA #IMPLIED>
56
  <!ATTLIST configOption type CDATA #IMPLIED>
56
  <!ATTLIST configOption type CDATA #IMPLIED>
57

    
   
57

   
58
  <!ELEMENT matchInfo (category|field?)>
58
  <!ELEMENT matchInfo (category|field?)>
59

    
   
59

   
60
  <!ELEMENT category (#PCDATA)>
60
  <!ELEMENT category (#PCDATA)>
61
  <!ATTLIST category match (yes|no|true|false) #REQUIRED>
61
  <!ATTLIST category match (yes|no|true|false) #REQUIRED>
62

    
   
62

   
63
  <!ELEMENT field (#PCDATA)>
63
  <!ELEMENT field (#PCDATA)>
64
  <!ATTLIST field name CDATA #REQUIRED>
64
  <!ATTLIST field name CDATA #REQUIRED>
65

    
   
65

   
66
  <!ELEMENT info (para|note|warning|variablelist|enumlist|info|xi:include)*>
66
  <!ELEMENT info (para|note|warning|variablelist|enumlist|info|xi:include)*>
67
  <!ATTLIST info name CDATA #REQUIRED>
67
  <!ATTLIST info name CDATA #REQUIRED>
68
  <!ATTLIST info language CDATA #REQUIRED>
68
  <!ATTLIST info language CDATA #REQUIRED>
69
  <!ATTLIST info tech CDATA #REQUIRED>
69
  <!ATTLIST info tech CDATA #REQUIRED>
70

    
   
70

   
71
  <!ELEMENT see-also (ref|xi:include)*>
71
  <!ELEMENT see-also (ref|xi:include)*>
72

    
   
72

   
73
  <!ELEMENT ref (#PCDATA)>
73
  <!ELEMENT ref (#PCDATA)>
74
  <!ATTLIST ref type (application|function|astcli|link|manpage|filename|agi|manager|managerEvent|configOption) #REQUIRED>
74
  <!ATTLIST ref type (application|function|astcli|link|manpage|filename|agi|manager|managerEvent|configOption) #REQUIRED>
75
  <!ATTLIST ref module CDATA #IMPLIED>
75
  <!ATTLIST ref module CDATA #IMPLIED>
76

    
   
76

   
77
  <!ELEMENT synopsis (#PCDATA)>
77
  <!ELEMENT synopsis (#PCDATA)>
78

    
   
78

   
79
  <!ELEMENT syntax (parameter|dataType|category|matchInfo|xi:include|channel_snapshot|bridge_snapshot)*>
79
  <!ELEMENT syntax (parameter|dataType|category|matchInfo|xi:include|channel_snapshot|bridge_snapshot)*>
80
  <!ATTLIST syntax argsep CDATA ",">
80
  <!ATTLIST syntax argsep CDATA ",">
81

    
   
81

   
82
  <!ELEMENT channel_snapshot (#PCDATA)>
82
  <!ELEMENT channel_snapshot (#PCDATA)>
83
  <!ATTLIST channel_snapshot prefix CDATA "">
83
  <!ATTLIST channel_snapshot prefix CDATA "">
84

    
   
84

   
85
  <!ELEMENT bridge_snapshot (#PCDATA)>
85
  <!ELEMENT bridge_snapshot (#PCDATA)>
86
  <!ATTLIST bridge_snapshot prefix CDATA "">
86
  <!ATTLIST bridge_snapshot prefix CDATA "">
87

    
   
87

   
88
  <!ELEMENT configOptionToEnum (configOption|xi:include)*>
88
  <!ELEMENT configOptionToEnum (configOption|xi:include)*>
89
  <!ATTLIST configOptionToEnum prefix CDATA "">
89
  <!ATTLIST configOptionToEnum prefix CDATA "">
90

    
   
90

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

    
   
92

   
93
  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
93
  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
94
  <!ATTLIST parameter name CDATA "">
94
  <!ATTLIST parameter name CDATA "">
95
  <!ATTLIST parameter required (yes|no|true|false) "false">
95
  <!ATTLIST parameter required (yes|no|true|false) "false">
96
  <!ATTLIST parameter multiple (yes|no|true|false) "false">
96
  <!ATTLIST parameter multiple (yes|no|true|false) "false">
97
  <!ATTLIST parameter hasparams (yes|no|true|false|optional) "false">
97
  <!ATTLIST parameter hasparams (yes|no|true|false|optional) "false">
98
  <!ATTLIST parameter literal (yes|no|true|false) "false">
98
  <!ATTLIST parameter literal (yes|no|true|false) "false">
99
  <!ATTLIST parameter default CDATA "">
99
  <!ATTLIST parameter default CDATA "">
100
  <!ATTLIST parameter argsep CDATA ",">
100
  <!ATTLIST parameter argsep CDATA ",">
101

    
   
101

   
102
  <!ELEMENT optionlist (option+)>
102
  <!ELEMENT optionlist (option+)>
103
  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|info|xi:include)*>
103
  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|info|xi:include)*>
104
  <!ATTLIST option name CDATA #REQUIRED>
104
  <!ATTLIST option name CDATA #REQUIRED>
105
  <!ATTLIST option argsep CDATA ",">
105
  <!ATTLIST option argsep CDATA ",">
106
  <!ATTLIST option implies CDATA "">
106
  <!ATTLIST option implies CDATA "">
107
  <!ATTLIST option hasparams CDATA "">
107
  <!ATTLIST option hasparams CDATA "">
108

    
   
108

   
109
  <!ELEMENT enumlist (configOptionToEnum|enum+)>
109
  <!ELEMENT enumlist (configOptionToEnum|enum+)>
110
  <!ELEMENT enum (para|note|warning|parameter|enumlist|info|xi:include)*>
110
  <!ELEMENT enum (para|note|warning|parameter|enumlist|info|xi:include)*>
111
  <!ATTLIST enum name CDATA "">
111
  <!ATTLIST enum name CDATA "">
112

    
   
112

   
113
  <!ELEMENT argument (para|note|warning|variablelist|argument|info|xi:include)*>
113
  <!ELEMENT argument (para|note|warning|variablelist|argument|info|xi:include)*>
114
  <!ATTLIST argument name CDATA #REQUIRED>
114
  <!ATTLIST argument name CDATA #REQUIRED>
115
  <!ATTLIST argument multiple (yes|no|true|false) "false">
115
  <!ATTLIST argument multiple (yes|no|true|false) "false">
116
  <!ATTLIST argument required (yes|no|true|false) "false">
116
  <!ATTLIST argument required (yes|no|true|false) "false">
117
  <!ATTLIST argument hasparams (yes|no|true|false|optional) "false">
117
  <!ATTLIST argument hasparams (yes|no|true|false|optional) "false">
118
  <!ATTLIST argument argsep CDATA ",">
118
  <!ATTLIST argument argsep CDATA ",">
119

    
   
119

   
120
  <!ELEMENT para (#PCDATA|astcli|literal|emphasis|filename|directory|replaceable|variable|xi:include)*>
120
  <!ELEMENT para (#PCDATA|astcli|literal|emphasis|filename|directory|replaceable|variable|xi:include)*>
121
  <!ELEMENT literal (#PCDATA)>
121
  <!ELEMENT literal (#PCDATA)>
122
  <!ELEMENT emphasis (#PCDATA)>
122
  <!ELEMENT emphasis (#PCDATA)>
123
  <!ELEMENT filename (#PCDATA)>
123
  <!ELEMENT filename (#PCDATA)>
124
  <!ELEMENT replaceable (#PCDATA)>
124
  <!ELEMENT replaceable (#PCDATA)>
125
  <!ELEMENT directory (#PCDATA)>
125
  <!ELEMENT directory (#PCDATA)>
126
  <!ELEMENT astcli (#PCDATA)>
126
  <!ELEMENT astcli (#PCDATA)>
127

    
   
127

   

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

    
   
129
  <!ATTLIST example title CDATA "">

    
   
130
  <!ATTLIST example language CDATA "" >

    
   
131

   
128
  <!ELEMENT note (para+|xi:include*)>
132
  <!ELEMENT note (para+|xi:include*)>
129
  <!ELEMENT warning (para+|xi:include*)>
133
  <!ELEMENT warning (para+|xi:include*)>
130

    
   
134

   
131
  <!ELEMENT variablelist (variable+|xi:include*)>
135
  <!ELEMENT variablelist (variable+|xi:include*)>
132
  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
136
  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
133
  <!ATTLIST variable name CDATA "">
137
  <!ATTLIST variable name CDATA "">
134

    
   
138

   
135
  <!ELEMENT value (#PCDATA)>
139
  <!ELEMENT value (#PCDATA)>
136
  <!ATTLIST value name CDATA #REQUIRED>
140
  <!ATTLIST value name CDATA #REQUIRED>
137
  <!ATTLIST value default CDATA "">
141
  <!ATTLIST value default CDATA "">
/trunk/funcs/func_jitterbuffer.c
Revision 418779 New Change
 
/trunk/main/xmldoc.c
Revision 418779 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.