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.

Currently, we support documenting files (eg. main.js), objects (eg. Applet.Applet), functions (including functions of files and functions of objects), signals and enums.

The documentation appears as a comment right before 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 prototype, 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.

1
2
3
4
5
6
7
8
9

function Applet() {
    this._init()
}

Applet.prototype = {
    _init: function() {

    }
}

The general format of a piece of code documentation is as follows:

1
2
3
4
5
6
7
8
9
10
11

/**
* name_of_thing:
* @short_description: one-line description
* @prop1 (type): description
* @prop2 (type): description
* @prop3 (type): description
*
* Long description
*
* Second paragraph of long description
*/

A comment block should always start with

1

/**

Avoid starting comments with this (use /* 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.

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:

1
2
3
4
5

* function_name:
* #ObjectName:
* FILE:filename.js
* ENUM:EnumName
* SIGNAL:signal-name

Note that we do not have to include the namespace of an object, ie. it is #ObjectName, not #FileName.ObjectName.

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

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,

1
2

* @prop (type): this is a very long description. Oh my gosh I am
* running out of space!

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,

1
2
3

* @prop1 (type): hello
*
* @prop2 (type): world

is fine, but two line breaks within a property description is not. eg

1
2
3
4

* @prop1 (type): line 1
*
* line 2
* @prop2 (type): hello world

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 \ character in place of the empty line, ie.

1
2
3
4

* @prop1 (type): line 1
* \
* line 2
* @prop2 (type): hello world

In the description section, two line breaks will be translated into an actual line break, and single line breaks are ignored.

At the end, in the case of a function, a return value can be specified in the form

1

* Returns (type): description of what is returned

Despite looking like a property, the description can in fact have multiple paragraphs. The following is valid

1
2
3
4

* Returns (type): hey this function returns a really cool thing!
* Want to know what it is?
*
* It is a random number!

Objects should indicate what they directly inherit in the description, using the form

1

* Inherits: Applet.Applet

Note that the namespace is required.