doc/dbusxml.doc

   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 */