CK D-Bus docs

[Rob Taylor]

CCing D-Bus mailing list for wider input..

William Jon McCann wrote:
> On 3/10/07, William Jon McCann <mccann at jhu.edu> wrote:
>> I think it is much simpler to just define a small set of documentation
>> tags that we allow to be used inside a <docstring> block.  And with
>> those tags we should probably stay closer to gtk-doc and docbook than
>> xhtml (which should probably be reserved for use as one of the views
>> of this data rather than the source model).  I'll try to play with
>> this and come up with a concrete proposal.
> 
> So, apparently other parties have investigated this type of thing already:
> http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp
> 
> 
> And this actually looks pretty nice to me.  But maybe with <ref
> type="parameter|signal|method|object|service"> instead of just
> <paramref>.
> 
> The <permission> tag is particularly important for objects on the
> system bus like HAL and CK.
> 
> So to summarize, I think perhaps we should allow any tag to contain a
> <doc></doc> block to document it.  And that doc block can contain any
> of these tags.  This will make it easy for the bindings parser to just
> ignore that whole block.  Or, alternately, these tags could be added
> to the D-Bus introspection format officially so that lowlevel D-Bus
> apps like HAL, gnome-screensaver, etc can automatically export
> documentation too.
> 
> Thoughts?

These look nice to me too!

Simon, what do you think?

Rob