Use doxymel for documentation.

1 files changed, 150 insertions, 118 deletions

diff --git a/libdbusmenu-glib/dbus-menu.xml b/libdbusmenu-glib/dbus-menu.xml
index 866969e..692158e 100644
--- a/libdbusmenu-glib/dbus-menu.xml
+++ b/libdbusmenu-glib/dbus-menu.xml
@@ -27,65 +27,107 @@ You should have received a copy of both the GNU Lesser General Public
 License version 3 and version 2.1 along with this program.  If not, see 
 <http://www.gnu.org/licenses/>
 -->
-<node name="/">
+<node name="/" xmlns:dox="http://www.ayatana.org/dbus/dox.dtd">
 	<interface name="org.ayatana.dbusmenu">
+		<dox:d><![CDATA[
+		The goal of this DBus interface is to be able to pass menu items
+		through DBus.
+
+		Items are represented with a unique numeric id and a dictionary of
+		properties.
+
+		Available properties are:
+
+		- @c type (string): Type of the item (see below)
+		- @c label (string): Text of the item
+		- @c icon-data (binary): Raw data of the icon (TODO: define format)
+		- @c icon (string): Icon name of the item, following icon spec
+		- @c sensitive (boolean): Whether the item can be activated or not
+		- @c checked (boolean): Whether a checkbox or radio item is checked
+		- @c shortcut (string): The keyboard shortcut
+
+		Vendor specific properties can be added by prefixing them with "x-<vendor>-"
+
+		@c type property is an enum which can take the following values:
+
+		- @c action: An item which can be clicked to trigger an action
+		- @c checkbox: An item which can be checked or unchecked
+		- @c radio: An item which can be checked or unchecked as part of a group
+		- @c separator: A separator
+		- @c menu: An item which contains more items
+
+		Vendor specific types can be added by prefixing them with "x-<vendor>-"
+		]]></dox:d>
 
 <!-- Properties -->
-<!--
-Provides the version of the DBusmenu API that this API is
-implementing.
--->
-		<property name="version" type="u" access="read"/>
+		<property name="version" type="u" access="read">
+			<dox:d>
+			Provides the version of the DBusmenu API that this API is
+			implementing.
+			</dox:d>
+		</property>
 
 <!-- Functions -->
 
-<!--
-Provides an XML representation of the menu hierarchy
-
-@param parentId The ID of the parent node for the layout.  For
-	grabbing the layout from the root node use zero.
-@param revision The revision number of the layout.  For matching
-	with layoutUpdated signals.
-@param layout The layout as an XML string of IDs.
-
-XML syntax:
-
-<menu id="1"> # Root container
-  <menu id="2"> # First level menu, for example "File"
-    <menu id="3"/> ~ Second level menu, for example "Open"
-    <menu id="4"/>
-    ...
-  </menu>
-  <menu id="5"> # Another first level menu, say "Edit"
-    ...
-  </menu>
-  ...
-</menu>
--->
 		<method name="GetLayout">
-			<arg type="u" name="parentId" direction="in" />
-			<arg type="u" name="revision" direction="out" />
-			<arg type="s" name="layout" direction="out" />
+			<dox:d><![CDATA[
+			Provides an XML representation of the menu hierarchy
+
+			XML syntax:
+
+			@verbatim
+			<menu id="1" revision="2"> # Root container
+			  <menu id="2" revision="2"> # First level menu, for example "File"
+				<menu id="3" revision="2"/> ~ Second level menu, for example "Open"
+				<menu id="4" revision="3"/>
+				...
+			  </menu>
+			  <menu id="5" revision="2"> # Another first level menu, say "Edit"
+				...
+			  </menu>
+			  ...
+			</menu>
+			@endverbatim
+			]]></dox:d>
+			<arg type="u" name="parentId" direction="in">
+				<dox:d>The ID of the parent node for the layout.  For
+				grabbing the layout from the root node use zero.</dox:d>
+			</arg>
+			<arg type="u" name="revision" direction="out">
+				<dox:d>The revision number of the layout.  For matching
+				with layoutUpdated signals.</dox:d>
+			</arg>
+			<arg type="s" name="layout" direction="out">
+				<dox:d>The layout as an XML string of IDs.</dox:d>
+			</arg>
 		</method>
 
-<!--
-Returns the list of items which are children of @a parentId.
-
-@param Ids A list of ids that we should be finding the properties
-	on.  If the list is empty, all menu items should be sent.
-@param propertyNames list of string the list of item properties we
-	are interested in.  If there are no entries in the list all of
-	the properties will be sent.
-
-An item is represented as a struct following this format:
-@li id unsigned the item id
-@li properties map(string => variant) the requested item properties
-
--->
 		<method name="GetGroupProperties">
-			<arg type="au" name="Ids" direction="in" />
-			<arg type="as" name="propertyNames" direction="in" />
-			<arg type="a(ua{sv})" name="properties" direction="out" />
+			<dox:d>
+			Returns the list of items which are children of @a parentId.
+			</dox:d>
+			<arg type="au" name="Ids" direction="in" >
+				<dox:d>
+					A list of ids that we should be finding the properties
+					on.  If the list is empty, all menu items should be sent.
+				</dox:d>
+			</arg>
+			<arg type="as" name="propertyNames" direction="in" >
+				<dox:d>
+					list of string the list of item properties we are
+					interested in.  If there are no entries in the list all of
+					the properties will be sent.
+				</dox:d>
+			</arg>
+			<arg type="a(ua{sv})" name="properties" direction="out" >
+				<dox:d>
+					An array of property values.
+					An item in this area is represented as a struct following
+					this format:
+					@li id unsigned the item id
+					@li properties map(string => variant) the requested item properties
+				</dox:d>
+			</arg>
 		</method>
 
 		<method name="GetChildren">
@@ -94,99 +136,89 @@ An item is represented as a struct following this format:
 			<arg type="a(ua{sv})" name="properties" direction="out" />
 		</method>
 
-<!--
-Each menu item has a set of properties. Property keys are in menuitem.h:
-
-@li type string Type of the item (see below)
-@li label string Text of the item
-@li icon-data binary Raw data of the icon (TODO: define format)
-@li icon string Icon name of the item, following icon spec
-@li sensitive boolean Whether the item can be activated or not
-@li visible boolean Whether the item is visible or not (XXX: Is this necessary?)
-@li checked boolean Whether a checkbox or radio item is checked
-@li shortcut string The keyboard shortcut
-
-@c type property is an enum which can take the following values (client.h):
-
-@li action An item which can be clicked to trigger an action
-@li checkbox An item which can be checked or unchecked
-@li radio An item which can be checked or unchecked as part of a group
-@li separator A separator
-@li menu An item which contains more items
--->
 		<method name="GetProperty">
 			<arg type="u" name="id" direction="in" />
 			<arg type="s" name="name" direction="in" />
 			<arg type="v" name="value" direction="out" />
 		</method>
 
-<!--
-Returns multiple properties in one call. This is more efficient than
-GetProperty.
-
-@param id unsigned the item whose properties we want to retrieve.
-@param propertyNames list of string name of the properties we want.  If the list contains no entries, all properties are sent.
--->
 		<method name="GetProperties">
+			<dox:d>
+			Returns multiple properties in one call. This is more efficient than
+			GetProperty.
+
+			</dox:d>
 			<annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QVariantMap"/>
-			<arg type="u" name="id" direction="in" />
-			<arg type="as" name="propertyNames" direction="in" />
+			<arg type="u" name="id" direction="in" >
+				<dox:d>The item whose properties we want to retrieve.</dox:d>
+			</arg>
+			<arg type="as" name="propertyNames" direction="in" >
+				<dox:d>List of string name of the properties we want.  If the list contains no entries, all properties are sent.</dox:d>
+			</arg>
 			<arg type="a{sv}" name="properties" direction="out" />
 		</method>
 
-<!--
-This is called by the applet to notify the application an event happened on a
-menu item.
-
-@param id the id of the item which received the event
-@param type the type of event
-@param data event-specific data
-@param timestamp The time that the event occured if available or the time the message was sent if not.
-
-@a type can be one of the following:
-
-@li "clicked"
-@li "hovered"
-
-Vendor specific events can be added by prefixing them with "x-<vendor>-"
--->
 		<method name="Event">
-			<arg type="u" name="id" direction="in" />
-			<arg type="s" name="eventId" direction="in" />
-			<arg type="v" name="data" direction="in" />
-			<arg type="u" name="timestamp" direction="in" />
+			<dox:d><![CDATA[
+			This is called by the applet to notify the application an event happened on a
+			menu item.
+
+			@a type can be one of the following:
+
+			@li "clicked"
+			@li "hovered"
+
+			Vendor specific events can be added by prefixing them with "x-<vendor>-"
+			]]></dox:d>
+			<arg type="u" name="id" direction="in" >
+				<dox:d>the id of the item which received the event</dox:d>
+			</arg>
+			<arg type="s" name="eventId" direction="in" >
+				<dox:d>the type of event</dox:d>
+			</arg>
+			<arg type="v" name="data" direction="in" >
+				<dox:d>event-specific data</dox:d>
+			</arg>
+			<arg type="u" name="timestamp" direction="in" >
+				<dox:d>The time that the event occured if available or the time the message was sent if not</dox:d>
+			</arg>
 		</method>
 
 <!-- Signals -->
-<!--
-Triggered by the application to notify the applet that the property @a property
-from item @a id has changed to @a value.
--->
 		<signal name="ItemPropertyUpdated">
+			<dox:d>
+			Triggered by the application to notify the applet that the property @a property
+			from item @a id has changed to @a value.
+			</dox:d>
 			<arg type="u" name="id" direction="out" />
 			<arg type="s" name="prop" direction="out" />
 			<arg type="v" name="value" direction="out" />
 		</signal>
 
-<!--
-Triggered by the application to notify the applet that all properties of item
-@a id should be considered outdated
--->
 		<signal name="ItemUpdated">
-			<arg type="u" name="id" direction="out" />
+			<dox:d>
+				Triggered by the application to notify the applet that all properties of item
+			</dox:d>
+			<arg type="u" name="id" direction="out" >
+				<dox:d>id which should be considered outdated</dox:d>
+			</arg>
 		</signal>
 
-<!--
-Triggered by the application to notify display of a layout update, up to
-revision
-@param revsion The revision of the layout that we're currently on
-@param parent  If the layout update is only of a subtree, this is the parent
-         item for the entries that have changed.  It is zero if the
-		 whole layout should be considered invalid.
--->
-		<signal name="LayoutUpdated">
-			<arg type="i" name="revision" direction="out" />
-			<arg type="u" name="parent" direction="out" />
+		<signal name="LayoutUpdate">
+			<dox:d>
+			Triggered by the application to notify display of a layout update, up to
+			revision
+			</dox:d>
+			<arg type="i" name="revision" direction="out" >
+				<dox:d>The revision of the layout that we're currently on</dox:d>
+			</arg>
+			<arg type="u" name="parent" direction="out" >
+				<dox:d>
+				If the layout update is only of a subtree, this is the
+				parent item for the entries that have changed.  It is zero if
+				the whole layout should be considered invalid.
+				</dox:d>
+			</arg>
 		</signal>
 
 <!-- End of interesting stuff -->