Open Source .NET Development [Electronic resources] نسخه متنی

NAnt Integration

Probably the best selling feature of NDoc is that it is already built into NAnt. That means it is very easy to integrate into the build process. Because of the complexity of the <ndoc> task in NAnt, I delayed the discussion until now. Listing 5.21 shows the NAnt <ndoc> task.

Listing 5.21. The NDoc NAnt task used to document the NAnt product

<ndoc failonerror="false">

<assemblies basedir="${build.dir}/bin">

<includes name="NAnt.Core.dll" />

<includes name="NAnt.*Tasks.dll" />

<includes name="NAnt.NUnit.dll" />

</assemblies>
<documenters>

<documenter name="MSDN">
<property name="OutputDirectory" value="${build.dir}/doc/sdk" />
<property name="HtmlHelpName" value="NAnt-SDK" />
<property name="HtmlHelpCompilerFilename" value="${projectl-help.dir}\hhc
.exe" />
<property name="IncludeFavorites" value="False" />
<property name="Title" value="NAnt SDK Documentation - v.${project.version}" />
<property name="ShowVisualBasic" value="True" />
<property name="ShowMissingSummaries" value="${build.debug}" />
<property name="ShowMissingRemarks" value="

${build.debug} " />
<property name="ShowMissingParams" value="${build.debug}" />
<property name="ShowMissingReturns" value="${build.debug}" />
<property name="ShowMissingValues" value="${build.debug}" />
<property name="DocumentInternals" value="False" />
<property name="DocumentPrivates" value="False" />
<property name="DocumentProtected" value="True" />
<property name="DocumentEmptyNamespaces" value="False" />
<property name="IncludeAssemblyVersion" value="False" />
<property name="CopyrightText" value="Copyright (C) 2001-2003 Gerry Shaw" />
<property name="CopyrightHref" value="http://nant.sourceforge.net" />
</documenter>
</documenters>
</ndoc>

Chapter 4, the NDoc task now is much simpler to understand. Remember that a fileset is a grouping of files. NDoc's Assemblies fileset lists the assemblies you want to include in your documentation. NDoc does not completely rely on just the C# XML documentation output of the compiler but also uses some reflection on its own to make the documentation more complete. Also notice in the second assembly in the fileset the clever usage of a patternset. Remember that a patternset is a pattern to match (in this case a wildcard character) that specifies all the different NAnt task dll files, and there are a lot. This saves you from having to list a number of dlls and decreases the chances of typos. In Listing 5.21, the NAnt team chose to use just one documentor, the MSDN documentor type. This documentor type produces a nice CHM file and, from the many Open Source projects I have seen, seems to be the most popular documentor type.

The many properties can be overwhelming, but in most situations, you can just cut and paste the example NDoc task from NAnt's documentation. Listing 5.21 only uses one documentor as its output, the aforementioned MSDN documenter, but the task does allow for many different documenter outputs. The example could output to Linear HTML or Javadoc as well, but that would have made the listing even more confusing. The outputdir element is where the output of the documentor will reside. The HtmlHelpName is the name of the CHM file. The include favorites tag allows you to include the favorites from Internet Explorer. Title controls the title of the CHM's window. The ShowVisualBasic element controls whether the function declarations are shown in the Visual Basic.NET language as well as C#. The ShowMissing* elements determine whether the items (Summary, Results, etc.) are shown even if they are empty because they are not in the original C# XML documentation. The Document* elements allow you to control what will be in the documentation. For example, do you want to include the private stuff in you documentation? IncludeAssemblyVersion is pretty self-explanatory. This is a great example of NDoc using reflection. The Copyright elements determine the copyright statement and URL at the bottom of each documentation page in the CHM file.

In Listing 5.21, the NAnt team used pretty much the standard NDoc property settings except for the ShowMissing properties. For those properties, they have tied the Boolean value to the build.debug property. Therefore, if you are building NAnt in Debug mode, the documentation will be more verbose (including missing things in the documentation) than a release build. This is a great idea to show the team where the missing documentation is when debugging, but it allows the release builds to be clean for the users of NAnt.

TIP

The process of creating the documentation via reflection and transforming the XML to the desired output can be expensive, although it is getting faster. This means you may want to add a new conditional target to your build specifically for documentation. This is a target you probably will not want to run with every build, but certainly with any builds that leave the engineering department.