[RFC] Standard documentation strings

[Sanel Zukan]

Hi,

Thank you guys for leaving the comments. I was intentionally hesitant
to reply immediately, just to leave more time to gathering replies.

Clearly, there is a room for improvement, so I will try to summarize
the view, add a couple of observations and ask you to comment the
further posts :)

> The <tp:*> elements originate from Telepathy. We intended our augmented
> introspection format (described on

Thank you for clarifying me <tp:docstring> tag and the reasons behind it.

In gdbus-codegen documentation [1] is clearly stated how content can
be in Docbook format, so why not to reuse this as the starting idea. Will
this suffice, Simon?

As you said, there could be tools that will preprocess that xml file
(maybe during compilation when binding tool is creating source code)
and can/will convert whatever markup into Docbook. However, I would
also propose adding additional attribute so it can be clearly stated
the content is in docbook format or 'plain', whatever plain can mean.

With this, we can be able to write quick and short documentation
without messing with Docbook tags or write Docbook tags and let
application deals with it. Maybe something like this:

<annotation name="org.freedesktop.DBus.DocString"
            value="This is plain string" />

or like:

<annotation name="org.freedesktop.DBus.DocString"
            docbook="true"
            value="
<title>Very simple book</title>
   <chapter xml:id=\"chapter_1\">
   " />

However, this can create unreadable content, but we will leave that to
the tools to parse it.

If we are going to complicate (or simplify, depending how you see it)
the matter, 'DocString.Short' can be introduced and there can be
clearly stated this:

  * org.freedesktop.DBus.DocString - will be used for detail
    documentation and examples and must be in Docbook format with
    escaped XML tags

  * org.freedesktop.DBus.DocString.Short - will be used for short
    briefs and must be plain text

Tools can rely on 'DocString.Short' to display it in e.g. tooltips
and extraction tools can use 'DocString' to create manuals, API
documentation and etc.

Why annotations but not dedicated tag? Simply because of
compatibility: DBus DTD doesn't have to be updated (annotation value
is CDATA anyways) so adding documentation is a matter of project
(which relies on DBus and exposes services) decision will it be easy
approachable or not.

What do you think about it?

[1] http://developer.gnome.org/gio/unstable/gdbus-codegen.html

Regards,
Sanel