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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<chapter id="documenting-source">
<title>Writing documentation in source</title>
<para>
The C part of Cinnamon can be documented using standard gtk-doc format, and there should be plenty of tutorials on that. The JavaScript part of Cinnamon can also be documented using something that resembles gtk-doc format.
</para>
<para> Currently, we support documenting files (eg. <code>main.js</code>), objects (eg. <code>Applet.Applet</code>), functions (including functions of files and functions of objects), signals and enums. </para>
<para> The documentation appears as a comment <emphasis>right before</emphasis> the thing it describes. In the case of a file, it should appear at the very beginning of the file. If a object is declared using <code>prototype</code>, then it can appear right before either the function declaration or the prototype declaration, ie. before line 1 or line 5 in the example below. The documentation of signal can be placed anywhere within the prototype scope since there is no proper declaration of signals in javascript.</para>
<informalexample>
<programlisting>
function Applet() {
this._init()
}
Applet.prototype = {
_init: function() {
}
}
</programlisting>
</informalexample>
<para>
The general format of a piece of code documentation is as follows:
</para>
<informalexample>
<programlisting>
/**
* name_of_thing:
* @short_description: one-line description
* @prop1 (type): description
* @prop2 (type): description
* @prop3 (type): description
*
* Long description
*
* Second paragraph of long description
*/
</programlisting>
</informalexample>
<para>
A comment block should always start with
</para>
<informalexample>
<programlisting>
/**
</programlisting>
</informalexample>
<para>
Avoid starting comments with this (use <code>/*</code> instead) even though the parser should be smart enough to not parse them, but if they look too like a piece of documentation, the parser might get confused.
</para>
<para> The next line is the name of the thing being documented. Function, object, signal, file and enum documentations are distinguished using this line. They should look, respectively, like this: </para> <informalexample>
<programlisting>
* function_name:
* #ObjectName:
* FILE:filename.js
* ENUM:EnumName
* SIGNAL:signal-name
</programlisting>
</informalexample>
<para>Note that we do not have to include the namespace of an object, ie. it is <code>#ObjectName</code>, not <code>#FileName.ObjectName.</code></para>
<para>Afterwards is a short description. This is only needed for files and objects, and will be ignored for functions. It is optional, but things look ugly without it. Note that it has to be short, hence the name. It is shown in the contents page in the form</para>
<informalexample>
Object.Name - short description
</informalexample>
<para>Afterwards, all the properties of the thing should be listed. A "property" is a globally accessible variable in the case of a file, a genuine property in the case of an object, a parameter for a function, an argument passed in the case of a signal, or an element of the enum for an enum. The type of the property is optional, but leaving it out makes the documentation less helpful and also more ugly (except for enums, where types should not appear). If the description is too long to fit in one line, break it into two rows using a *single* line break. Single line breaks are always ignored when parsing. For example,</para>
<informalexample>
<programlisting>
* @prop (type): this is a very long description. Oh my gosh I am
* running out of space!
</programlisting>
</informalexample>
<para>After the properties, a description of the thing should be given. Use *two* line breaks to signify the end of the properties section, and write as normal. It is okay to separate two properties with two line breaks. For example,</para>
<informalexample>
<programlisting>
* @prop1 (type): hello
*
* @prop2 (type): world
</programlisting>
</informalexample>
<para>is fine, but two line breaks within a property description is not. eg</para>
<informalexample>
<programlisting>
* @prop1 (type): line 1
*
* line 2
* @prop2 (type): hello world
</programlisting>
</informalexample>
<para>is bad (line 2 will be treated as a description of the object itself). Instead, if you want the property description to have multiple paragraphs, put a <code>\</code> character in place of the empty line, ie.</para>
<informalexample>
<programlisting>
* @prop1 (type): line 1
* \
* line 2
* @prop2 (type): hello world
</programlisting>
</informalexample>
<para>In the description section, two line breaks will be translated into an actual line break, and single line breaks are ignored.</para>
<para>At the end, in the case of a function, a return value can be specified in the form</para>
<informalexample>
<programlisting>
* Returns (type): description of what is returned
</programlisting>
</informalexample>
<para>Despite looking like a property, the description can in fact have multiple paragraphs. The following is valid</para>
<informalexample>
<programlisting>
* Returns (type): hey this function returns a really cool thing!
* Want to know what it is?
*
* It is a random number!
</programlisting>
</informalexample>
<para>Objects should indicate what they directly inherit in the description, using the form</para>
<informalexample>
<programlisting>
* Inherits: Applet.Applet
</programlisting>
</informalexample>
<para>Note that the namespace is required.</para>
<sect2>
<title>Automatic substitutions</title>
<para>The current parser is able to perform several substitutions:</para>
<itemizedlist>
<listitem>
The type of a property specified will be automatically converted to a link to the documentation of that type, if available.
</listitem>
<listitem>
In the description of items, <code>@word</code> will be automatically converted to code format, ie. enclosed within <code><code></code> tags.
</listitem>
<listitem>
In the description of items, <code>*text more text*</code> will be shown in italics and <code>**text more text**</code> will be shown in bold. Note that using <code>_underlines to highlight_</code> is not supported since the parser will confuse it with private variables.
</listitem>
<listitem>
Links to other objects can be done with a <code>#Hash</code>. If you are linking to an object within the same file, you may omit the namespace, eg. using <code>#Applet</code> in <code>Applet.AppletContextMenu</code>. However, if it is from a different file, the namespace must be included.
</listitem>
<listitem>
<para>
Links to functions, properties or enums of other objects with a <code>%percentage sign</code>. If you wish to link to functions of the same object, the following four are acceptable:
</para>
<itemizedlist>
<listitem><code>this.func</code></listitem>
<listitem><code>this.func()</code></listitem>
<listitem><code>func</code></listitem>
<listitem><code>func()</code></listitem>
</itemizedlist>
<para>
Of course, if it is a property, then you would never want to include the <code>()</code> brackets. To refer to functions of other objects, you have to type the full name of the object. The namespace can be omitted if the object is in the same file. For example, the following are acceptable (assuming you are inside <code>popupMenu.js</code>.
</para>
<itemizedlist>
<listitem><code>PopupMenu.PopupBaseMenuItem._init</code></listitem>
<listitem><code>PopupMenu.PopupBaseMenuItem._init()</code></listitem>
<listitem><code>PopupBaseMenuItem._init</code></listitem>
<listitem><code>PopupBaseMenuItem._init()</code></listitem>
</itemizedlist>
<para>
If there are functions, properties and enums that take the same name, the property will be linked to, unless the name ends with <code>()</code>, in which case it will always be a function. If a function and an enum have the same name, the whole thing will explode into pieces and don't do that. It is a bad idea to have things with the same name anyway.
</para>
</listitem>
<listitem>
Code blocks can be enclosed in descriptions as follows:
<informalexample>
<programlisting>
```
this.is = some + code
```
</programlisting>
</informalexample>
</listitem>
<listitem>
Unordered lists can be created as follows:
<informalexample>
<programlisting>
- List item 1
- List item 2
\
Continuing item 2 with `\`
No longer an item
</programlisting>
</informalexample>
Lists cannot be nested, but code blocks can appear in lists
</listitem>
</itemizedlist>
</sect2>
</chapter>
|
