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
|
Note: this is informal documentation, not a formal XML schema (though
one could write a complete schema from this information).
While it's always been assumed, the tag and attribute names *are*
case-sensitive.
The format of an -xmldocs file is:
<module>
<modsummary>
<!-- a summary of the purpose of the module -->
</modsummary>
<!-- conventionally, "data" first, then "fun", then "except", each in alphabetical order by name -->
<data>
<name>module::data</name>
<comment>
<!-- see below for contents of "comment" -->
</comment>
<location>
<file>Example.k</file>
<line>217</line>
</location>
<!-- one of these for each type variable in the data type -->
<param>a</param>
<!-- one of these for each constructor -->
<con>
<conname>Excon</conname>
<!-- one for each argument in the constructor, in the order they appear in the constructor -->
<arg>
<argname>val</argname>
<type>a</type>
</arg>
<arg>
<argname>count</argname>
<type>Int</type>
</arg>
</con>
</data>
<fun>
<!-- function names not qualified by module name -->
<name>exfun</name>
<!-- next empty tag present if function is deprecated -->
<deprecated/>
<comment>
<!-- again see below for contents -->
</comment>
<location>
<file>Example.k</file>
<line>94</line>
</location>
<!-- return type -->
<return>String</return>
<!-- one of these for each argument, in order -->
<!-- passby is either "copy" or "var" -->
<arg passby="copy">
<argname>str</argname>
<argtype>String</argname>
<!-- if the argument has a default value, then: -->
<defval>"hello"</defval>
</arg>
<arg passby="var">
<argname>i</argname>
<argtype>Int</argtype>
</arg>
</fun>
<except>
<name>module::Exception</name>
<comment>
<!-- see below for contents of "comment" -->
</comment>
<location>
<file>Example.k</file>
<line>54</line>
</location>
<!-- one of these for each argument, in order -->
<arg>
<argtype>String</argname>
</arg>
</except>
</module>
The format for the <comment> element is:
<comment>
<!-- one of these for each argument -->
<argument name="argname">A description of the argument</argument>
<!-- one of these -->
<summary>A one-line summary of the data type or function</summary>
<!-- zero or more of these, in any order -->
<prose>A description of the data type or function</prose>
<example>An example of code using this type or function</example>
<list>A list, containing one or more <item>...</item>s</list>
<!-- zero or more of these -->
<related>References to related functions, types, etc.</related>
</comment>
The <modsummary> element has the same format as the <comment> element,
but without <argument> or <related> sub-elements.
Each of the <argument>, <prose>, <example>, <item> or <related>
elements can contain the following elements as well as free text.
<variable> : A variable or parameter
<code> : Example code (outside an <example> element)
<input> : User input
<output> : Sample output
<emphasis> : Emphasis
<link> : A link to another resource. Has the required attribute "url" to
give the URL of that resource.
<functionref> : Another function in Kaya. Optional attribute "index"
to disambiguate overloaded names in the same
module. The content of this element is the
module::name of the function.
<moduleref> : A Kaya module. The content of the element is the module
name.
<dataref> : A data type in Kaya. The content of this element is the
module::name of the data type.
<exceptref> : An Exception in Kaya. The content of this element is the
module::name of the Exception.
|
