dbus-glib - removing the generated bus method wrappers

[Matthew Johnson]

On Tue, 25 Jul 2006, Havoc Pennington wrote:

> Matthew Johnson wrote:
>> 
>> IMHO this is a little complicated. I think the introspection data should
>> be sufficient (and auto-generated so that documentation JustHappens)
>> with a nice simple way to make it human readable, like my XSLT. Then you
>> just need to get the XML data and you're done.
>> 
>
> What I don't understand about this approach is how you deal with the 
> formatting of the docs. That is, how do you represent the equivalent of all 
> the @param etc. tags in javadoc, or the gtk-doc or Doxygen equivalents, or 
> Docbook markup?
>
I'll comment on javadoc, I don't know the others.

Javadoc has @param, @return, @throws tags and a description of the
function. You can also provide descriptions of classes/interfaces. If
annotations can be put on methods, interface, arguments; then the method
and interface documentation annotation can be written straight into the
javadoc comments and the annotations on <arg direction='in'> turned into
@param and the annotation on <arg direction='out'> turned into an
@return.

So:

<interface name="foo">
    <annotation name='doc' value='does stuff' />
    <method name='bar'>
       <annotation name='doc' value='does things' />
       <arg direction='in' type='i' name='baz'>
          <annotation name='doc' value='input' />
       </arg>
       <arg direction='out' type='i' >
          <annotation name='doc' value='output' />
       </arg>
    </method>
</interface>

would become:

/** does stuff.
*/
public interface foo
{
    /** does things.
       @param baz input
       @return output
    */
    public int bar(int baz);
}

for example. Actually, I would leave the annotations in the source in
java, since I can get at those at runtime to generate the XML from.

Matt

-- 
Matthew Johnson
http://www.matthew.ath.cx/