Documentation

Cake uses a combination of standard C# XML Documentation Comments and attributes to auto generate documentation to this site.

Classes

Classes purpose are documented with a summary tag and categorized using CakeAliasCategoryAttribute attribute.

/// <summary>
/// Contains functionality for working with GitReleaseManager.
/// </summary>
[CakeAliasCategory("GitReleaseManager")]
public static class GitReleaseManagerAliases
{...}

Methods

Methods purpose are documented with a summary tag, parameters with the param tag, if it returns somethings it's you use the returns tag and categorized using CakeAliasCategoryAttribute attribute.

Example usage is documented using the example tag and code tag for code.

/// <summary>
/// Makes the path absolute (if relative) using the current working directory.
/// </summary>
/// <example>
/// <code>
/// var path = MakeAbsolute(Directory("./resources"));
/// </code>
/// </example>
/// <param name="context">The context.</param>
/// <param name="path">The path.</param>
/// <returns>An absolute directory path.</returns>
[CakeMethodAlias]
[CakeAliasCategory("Path")]
public static DirectoryPath MakeAbsolute(this ICakeContext context, DirectoryPath path)
{...}

Properties

Properties purpose are documented with a summary tag and it's value described with the value tag.

/// <summary>
/// Gets or sets a value indicating whether to allow installation of prerelease packages.
/// This flag is not required when restoring packages by installing from packages.config.
/// </summary>
/// <value>
///   <c>true</c> to allow installation of prerelease packages; otherwise, <c>false</c>.
/// </value>
public bool Prerelease { get; set; }

Namespaces

Namespaces aren't documentable by default in the XML file format. Cake solves this by having an special internal class for each namespace called NamespaceDoc which are documented using the summary tag.

The convention is to place all these classes in common Namespaces.cs file per assembly.

namespace Cake.Common
{
    /// <summary>
    /// This namespace contain types used for common operations
    /// such as parsing release notes, retrieving arguments and
    /// to read and write environment variables.
    /// </summary>
    [CompilerGenerated]
    internal class NamespaceDoc
    {
    }
}