1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
Problem
=======
The initial goal was simply to create a docbook reference for each
interface - because it is standard and it is easy to convert into just
about anything else. After having hand coded docbook for few projects
and finding that difficult to maintain, I looked at some alternatives.
It was a specific non-goal to any docbook markup directly.
Relevant Art
==========
[many probably already know this already, but for completeness]
1. gtk-doc
I particularly like the output and ease of use of gtk-doc. It is
pretty powerful because it uses a simple semantic markup and is
contextual. The contextual part is interesting to me for a few
reasons:
a) you can use the structure of project instead of duplicating the
structure in another format
b) related to a. - you may be able to pull from the context content
implicitly instead of documenting it explicitly (ie. determine the
class name when documenting a method)
c) documentation is in proximity to the code that it describes which
makes it easier to maintain and view
For example, with C code gtk-doc scans for things like:
/**
* g_markup_parse_context_new:
* @parser: a #GMarkupParser
* @flags: one or more #GMarkupParseFlags
* @user_data: user data to pass to #GMarkupParser functions
* @user_data_dnotify: user data destroy notifier called when the
parse context is freed
*
* Creates a new parse context. A parse context is used to parse
* marked-up documents. You can feed any number of documents into
* a context, as long as no errors occur; once an error occurs,
* the parse context can't continue to parse text (you have to free it
* and create a new parse context).
*
* Return value: a new #GMarkupParseContext
**/
As you can see this uses an efficient markup that is described here:
http://svn.gnome.org/viewcvs/gtk-doc/trunk/doc/gnome.txt?revision=349&view=markup
2. C# documentation
Apparently, C# has a convention for adding contextual documentation
too. It is described here:
http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
and
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp
It is similar to gtk-doc in that it is contextual and is usually
contained in source code. However, instead of brewing its own kind of
markup it uses XML.
3. Java Doc
Quite similar to gtk-doc (or perhaps I have that reversed)
http://en.wikipedia.org/wiki/Javadoc
4. Telepathy spec
It extends the D-Bus introspection format to include documentation.
It does this by adding a <tp:docstring> element that may contain
XHTML. It too is contextual since the docstring may be added as a
child of any element. There are also tags defined for providing
copyright, etc
http://telepathy.freedesktop.org/wiki/DbusSpec
Review
======
I didn't know about the Telepathy docs initially - so it wasn't in the mix.
I valued:
* the capabilities of the gtk-doc and javadoc systems
* the high semantic value of the gtk-doc, javadoc, and C# doc systems
* the ability to extend/enrich the C# docs
* the ability to use XSLT etc to easily translate the C# docs
* the language/location independence of the C# docs (can be used in
source code or separately)
I didn't like:
* gtk-doc and javadoc relied on a custom markup
* that gtk-doc and javadoc aren't useful outside of source code
* that the XML tags used by C# docs were pretty specific to the language
* that with gtk-doc and javadoc you must duplicate some information that
can be found using the context (ie. function names etc)
And I prototyped few different things.
Results
======
So, there are really two separate but highly related problems. One is
defining a markup specification and the other is determining the
integration point.
This presumes that the two can be separated and so this became a
design goal. D-Bus different in this respect - all the other
contextual documentation is to some degree language specific.
- Markup
The C# docs use a clearly superior markup. However, it is somewhat C#
language specific. So, I tried to define a new set of elements that
would closely match the capabilities of the various systems.
In the process of actually producing docbook with it I came up with this:
http://gitweb.freedesktop.org/?p=ConsoleKit.git;a=blob;hb=HEAD;f=doc/dbus-introspect-docs.dtd
You may notice that there is one detail that makes it not orthogonal to...
- Integration point
The markup assumes that the integration point is capable of somehow
providing context.
I took it as a given that D-Bus already has a well defined (and
deployed) structural markup in the Introspect format. And that this
is in principle the common factor between all implementations and
bindings.
So, this seems to be the most likely point for documentation
integration. Even if it is a trade-off because it is more separated
from the code at least it is integrated with the "interface". And at
the end of the day, that may be more important and useful.
That said, the C# docs show that this doesn't preclude one from using
this same markup in source code. And so it should still be possible
to autogenerate from inline comments. The only difficulty would be
figuring out how to provide the <arg> context.
In the end I came to a conclusion that was similar to the Telepathy
spec but differed slightly due to the goal. I wanted to create a
docbook and thus needed to retain more semantic information. So, I
didn't use xhtml directly but defined a new DTD.
-- Jon McCann <mccann@jhu.edu>
|
