CK D-Bus docs

[William Jon McCann]

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?

Jon