|
1 /*! \page dbusxml DBus XML output format |
|
2 |
|
3 \addindex dbusxml |
|
4 |
|
5 <p>Doxygen can generate documentation for DBus XML files. This way |
|
6 DBus interfaces can be annotated with doxygen style comments, and |
|
7 without writing custom XML parsers. Doxygen extracts its text from |
|
8 all XML comments starting with '*' or '!'. An additional '<' can be |
|
9 used to assign the documentation string to the previous entity instead |
|
10 of the one following the comment. |
|
11 |
|
12 Note that before the parsing of DBus XML file works one has to |
|
13 assign the .xml extension to the DBus XML parser using the |
|
14 following configuration option: |
|
15 |
|
16 \verbatim |
|
17 EXTENSION_MAPPING = xml=dbusxml |
|
18 \endverbatim |
|
19 |
|
20 \section dbusxml_supported Supported XML elements and attributes |
|
21 |
|
22 <p>The following DBus XML elemets can be annotated: |
|
23 |
|
24 <ul> |
|
25 <li><b>interface</b> |
|
26 |
|
27 <li><b>method</b> or <b>signal</b> |
|
28 |
|
29 <li><b>arg</b> |
|
30 |
|
31 <li><b>property</b> |
|
32 |
|
33 </ul> |
|
34 |
|
35 Additional elements are supported. These are available once |
|
36 the xmlns "http://psiamp.org/dtd/doxygen_dbusxml.dtd" is |
|
37 available. |
|
38 |
|
39 <ul> |
|
40 <li><b>namespace</b>: This can be used to group other more of the |
|
41 additional elemets. This element requires a <b>name</b> attribute. |
|
42 |
|
43 <li><b>enum</b> is used to define enums. <b>value</b> element is |
|
44 then used to define the individual values in the enum. This element |
|
45 requires the <b>name</b> and <b>type</b> attributes. A |
|
46 optional <b>named-type</b> attribute is allowed, referrencing typed |
|
47 previously defined by one of the additional elements. A enum name |
|
48 can be used anywhere a type is required using the <b>named-type</b> |
|
49 attribute. |
|
50 |
|
51 <li><b>flagset</b> is used to define sets of flags. Required and |
|
52 optional attributes are identical to the ones used by <b>enum</b>. |
|
53 While <b>enum</b>s assume the values to be consecutive, while |
|
54 a <b>flagset</b> is values suitable for flags. A flagset name |
|
55 can be used anywhere a type is required using the <b>named-type</b> |
|
56 attribute. |
|
57 |
|
58 <li><b>struct</b> is used to define structures. A <b>name</b> |
|
59 attribute is required. |
|
60 |
|
61 <li><b>member</b> is used to define members of <b>structs</b>. It |
|
62 is valid inside <b>struct</b> elements. This |
|
63 element requires <b>name</b> and <b>type</b> attributes. In |
|
64 addition to (or even instead of) the <b>type</b> attribute a |
|
65 <b>named-type</b> attribute may be used to reference types defined |
|
66 by <b>enum</b>, <b>flagset</b> or <b>struct</b>. |
|
67 |
|
68 \section dbusxml_example Example |
|
69 |
|
70 <pre> |
|
71 <?xml version="1.0" ?> |
|
72 <!-- Comment --> |
|
73 <!--*< File comment --> |
|
74 <node name="/SomeNode" xmlns:dx="http://psiamp.org/dtd/doxygen_dbusxml.dtd"> |
|
75 <!--* test struct outside a namespace and interface --> |
|
76 <dx:struct name="StructOutsideNamespace"> |
|
77 <!--* member 1 --> |
|
78 <dx:member name="member1" type="s"/> |
|
79 <!--* complex member 1 --> |
|
80 <dx:member name="complexMember1" type="(ssu)"/> |
|
81 </dx:struct> |
|
82 |
|
83 <!--* Test flag set --> |
|
84 <dx:flagset name="flagset"> |
|
85 <!--* Flag 1 of flagset. --> |
|
86 <dx:value name="FLAG1"/> |
|
87 </dx:flagset> |
|
88 |
|
89 <!--* namespace comment --> |
|
90 <dx:namespace name="SomeNamespace"> |
|
91 <!--* struct inside a namespace --> |
|
92 <dx:struct name="StructInNamespace"> |
|
93 <!--* member 2 --> |
|
94 <dx:member name="member2" type="s"/> |
|
95 </dx:struct> |
|
96 </dx:namespace> |
|
97 <!--* Documentation on the interface --> |
|
98 <interface name="nl.stack.doxygen.test.interface"> |
|
99 <!--* Test Enum documentation --> |
|
100 <dx:enum name="TestEnum"> |
|
101 <!--* key 1 with value 13 --> |
|
102 <dx:value name="KEY1" value="13"/> |
|
103 <!--* key 2 without a value --> |
|
104 <dx:value name="KEY2"/> |
|
105 </dx:enum> |
|
106 |
|
107 <!--* struct inside a interface --> |
|
108 <dx:struct name="StructInInterface"> |
|
109 <!--* member 3 --> |
|
110 <dx:member name="member3" type="s"/> |
|
111 <!--* Struct in a struct --> |
|
112 <dx:struct name="StructInAStruct"> |
|
113 <!--* member4 --> |
|
114 <dx:member name="member4" type="s"/> |
|
115 </dx:struct> |
|
116 <!--* struct member --> |
|
117 <dx:member name="structMembor" type="(s)" named-type="StructInAStruct"/> |
|
118 </dx:struct> |
|
119 <!--* Document method |
|
120 |
|
121 Some extended documentation for the method. |
|
122 |
|
123 @param[in] input blah. |
|
124 @param[out] output blub |
|
125 --> |
|
126 <method name="method"> |
|
127 <arg direction="in" name="input" type="(s(s))" named-type="::nl::stack::doxygen::test::interface::StructInInterface"/> |
|
128 <arg direction="out" type="v" name="output"/> |
|
129 </method> |
|
130 |
|
131 <signal name="signal"> |
|
132 <!--*< Documentation for signal. |
|
133 |
|
134 @param parameter some parameter. |
|
135 --> |
|
136 <arg name="parameter" type="s"/> |
|
137 </signal> |
|
138 |
|
139 <!--* property documentation --> |
|
140 <property name="property" type="s" access="readwrite"/> |
|
141 |
|
142 <!--* property documentation read-only --> |
|
143 <property name="propertyRead" type="s" access="read"/> |
|
144 <!--* property documentation write-only --> |
|
145 <property name="propertyWrite" type="s" access="write"/> |
|
146 </interface> |
|
147 </node> |
|
148 </pre> |
|
149 */ |