History

Wiki »

User Documentation

A task that is often considered as a necessary evil, but it's really needed to document how stuff works :-)

Creating the documentation for the wiki is in fact easier as it may seem, we extract it from the source!
This means that you just create the documentation in the same editor where you the write code, using the same comment tags as in C# (or mostly the same comment tags). All elements with a Reflector attribute will be extracted, and used for the documentation. The docGenerator program in the Tools folder takes care of this.

The following elements are used :

summary This is the main explanation of the element, when on a class it will be displayed at the top of the page. This is the main explanation of the element. On a property it will be shown in the Configuration Elements table.
title Used inside the summary element of the class, if not specified the class name will be used. This gives a more friendly name for the page.
version Used to make clear from what version of CCNet the functionality is available. Can be used at class or property level.
code To provide a code or config example of how things must be used, this must be escaped XML. Meaning do not type 1<exec command="abc" /> but type it like so : 
1&lt;exec command="abc" /&gt;
inside the code element. Indention is not needed, this is automatically done through the wiki. If there are multiple configs, you can give each of them a separate title via the title attribute.
para Used to create paragraphs into the documentation. So use it as a child element of summary or remarks
heading creates a sub heading in section, like para or summary
b outputs the enclosed text as bold
link provides a link to another wiki page. For example you could provide links to similare topics like modification reader and modification writer
showChildren shows any childpages of the current page. This means that the class knows the wiki-layout, so use with caution.
includePage includes the contents of the involved page into this page/ Most used example are the integration properties on each task or publisher.

Example

Below is the comment of the Executable Task

 1    /// <summary>
 2    /// <para>
 3    /// The Executable Task lets you invoke any command line executable. It doesn't offer as much specific
 4    /// integration as (for example) the <link>NAnt Task</link>, but does allow you to hook almost anything
 5    /// up as a build process to CCNet. CCNet will examine the exit code when the executable ends and act
 6    /// accordingly.
 7    /// </para>
 8    /// </summary>
 9    /// <title>Executable Task</title>
10    /// <version>1.0</version>
11    /// <example>
12    /// &lt;code title="Minimalist example"&gt;
13    /// &amp;lt;exec executable="c:\projects\myproject\build.bat" /&amp;gt;
14    /// &lt;/code&gt;
15    /// &lt;code title="Full example"&gt;
16    /// &amp;lt;exec&amp;gt;
17    /// &amp;lt;executable&amp;gt;make&amp;lt;/executable&amp;gt;
18    /// &amp;lt;baseDirectory&amp;gt;D:\dev\MyProject&amp;lt;/baseDirectory&amp;gt;
19    /// &amp;lt;buildArgs&amp;gt;all&amp;lt;/buildArgs&amp;gt;
20    /// &amp;lt;buildTimeoutSeconds&amp;gt;10&amp;lt;/buildTimeoutSeconds&amp;gt;
21    /// &amp;lt;successExitCodes&amp;gt;0,1,3,5&amp;lt;/successExitCodes&amp;gt;
22    /// &amp;lt;environment&amp;gt;
23    /// &amp;lt;variable&amp;gt;
24    /// &amp;lt;name&amp;gt;MyVar1&amp;lt;/name&amp;gt;
25    /// &amp;lt;value&amp;gt;Var1Value&amp;lt;/value&amp;gt;
26    /// &amp;lt;/variable&amp;gt;
27    /// &amp;lt;variable name="MyVar2" value="Var2Value"/&amp;gt;
28    /// &amp;lt;/environment&amp;gt;
29    /// &amp;lt;/exec&amp;gt;
30    /// &lt;/code&gt;
31    /// &lt;/example&gt;
32    /// &lt;remarks&gt;
33    /// &lt;para type="note"&gt;
34    /// An exit code of -1 is always treated as the operation has timed out. This will fail the build.
35    /// &lt;/para&gt;
36    /// &lt;para type="warning"&gt;
37    /// Windows seems to change the case of environment variables occasionally. If your task target doesn't
38    /// find one of these properties, try using all upper case or all lower case versions of these properties.
39    /// &lt;/para&gt;
40    /// &lt;heading&gt;Frequently Asked Questions&lt;/heading&gt;
41    /// &lt;para&gt;
42    /// &lt;b&gt;Does the exec task pass the integration properties via the command line?&lt;/b&gt;
43    /// &lt;/para&gt;
44    /// &lt;para&gt;
45    /// No. The integration properties are only available as environment variables. As there is no way of
46    /// knowing the way in which the external program expects these properties to be formatted as command line
47    /// arguments, environment variables are a simple, common medium for making these values accessible. To
48    /// pass these environment variables into an external program, have the exec task call a batch file instead
49    /// that will pick up the environment variables, format them and pass them as command line arguments to the
50    /// external program.
51    /// &lt;/para&gt;
52    /// &lt;para&gt;
53    /// &lt;b&gt;Using built in shell commands&lt;/b&gt;
54    /// &lt;/para&gt;
55    /// &lt;para&gt;
56    /// In Windows use cmd.exe as the executable, and pass the wanted command as an argument, preceded with /c.
57    /// This allows to execute del *.* and the like. For example :
58    /// &lt;/para&gt;
59    /// &lt;code&gt;
60    /// &amp;lt;exec&amp;gt;
61    /// &amp;lt;executable&amp;gt;c:\Windows\System32\cmd.exe&amp;lt;/executable&amp;gt;
62    /// &amp;lt;buildArgs&amp;gt;/C NET STOP "Service name"&amp;lt;/buildArgs&amp;gt;
63    /// &amp;lt;/exec&amp;gt;
64    /// &lt;/code&gt;
65    /// &lt;para&gt;
66    /// The following parameters are passed to the external program using environment variables, in addition to those you specify in
67    /// the &amp;lt;environment&amp;gt; element.:
68    /// &lt;/para&gt;
69    /// &lt;includePage&gt;Integration_Properties&lt;/includePage&gt;
70    /// &lt;/remarks&gt;
71    [ReflectorType("exec")]
72    public class ExecutableTask
73