Getting unit testing code into XML Comment

Question

I am trying to comment an API (.Net) that I am exposing to a customer. I am doing this by using XML comments, and extracting via SandCastle.

This is all fine and dandy, however I have unittesting for the API, and thought the code from these would be good to place in the example tags.

So does anyone know of a good way to extract unit test code and place in the example tags? Or does anyone have better ideas?

Of course I redistribute the unit tests with the API, but it would be good to have them in the documentation.

Answer 1

I am using NUnit and Sandcastle Help File Builder. Please take a look at Sandcastle Help File Builder documentation about The Code Block Component.

Here is an example how I place unit tests code in the example tag:

    /// <summary>
    /// Returns a string representation of an object.
    /// </summary>
    /// <returns>Comma separated string.</returns>
    /// <example>
    /// <code source="UnitM.CentrallProcessingLib.Tests\Data\CSVDataRowTests.cs" region="ToString_a" />
    /// </example>
    public override string ToString()
    {
        return this.Data;
    }

Here is a referenced unit test (CSVDataRowTests.cs) (it should be inside the #region section):

  #region ToString_a

    [Test]
    public void ToString_a()
    {
        CSVDataRow res = new CSVDataRow 
        {
            Data = "1;2;3"
        };

        Assert.AreEqual(res.ToString(), res.Data);
    }

  #endregion

Best regards.