Click here to Skip to main content
15,879,184 members
Articles / Programming Languages / C#

Make NDoc compile the code examples contained in your documentation using NLiterate

Rate me:
Please Sign up or sign in to vote.
4.64/5 (19 votes)
26 Apr 20047 min read 122.7K   622   42  
An utility that merges and recompiles the examples in your documentation using NDoc.
Language:CS
EntryPoint:False
Source Xml code:
<member name="T:NLiterate.Example.XString"><summary><para>
            To demonstrate the use Literate Documentation using DocCompiler 
            for .NET programming, we define a simple string class.
            </para></summary><remarks><!-- this tag is configure NLiterate --><literate><reference assembly="System.dll" /></literate><para>
            We call our class <see cref="T:NLiterate.Example.XString" /> rather than <see cref="T:System.String" /> 
            to avoid confusion with the original and other (more useful) string classes.
            </para><code id="structure" title="XString declaration" compilable="true" entry-point="false" language="cs" hidden-namespace="Test">
            using System;
            
            public class XString
            {
            	{[privatefields Private Fields]}
            	{[constrpropmethods Methods]}
            }
            </code><para>
            The <see cref="T:NLiterate.Example.XString" /> is represented internally by an array of char:
            <code id="privatefields" title="XString representation">
            private char[] data;
            </code></para><para>
            The available manipulators on the class are separated in the following groups:
            <code id="constrpropmethods" title="XString members">
            {[constructors Constructors ]}
            {[properties Some properties]}
            {[methods]}
            </code></para><para>
            Our simple string class support the empty constructor only:
            </para><code id="constructors" title="Constructors">
            public XString()
            {}
            </code><para>
            The length of the string is accessed through the <see cref="!:Length" /> property:
            </para><code id="properties" title="Length Property">
            public int Length
            {
            	get
            	{
            		return this.data.Length;
            	}
            }
            </code><para>
            The <see cref="!:ToString" /> method is overloaded to return the data:
            </para><code id="methods" title="ToString Method">
            public override String ToString()
            {
            	return new String(this.data);
            }
            {[hashcode Hash code computation method]}
            </code><para>
            The hash code of the string is computed ....
            </para><code id="hashcode" title="GetHashCode">
            public override int GetHashCode()
            {
                return -1;
            }
            </code></remarks></member>
MergedCode:
namespace Test
{

            using System;
            
            public class XString
            {
            	
//<code id="privatefields" title="XString representation">

            private char[] data;
            
//</code>
            	
//<code id="constrpropmethods" title="XString members">

            
//<code id="constructors" title="Constructors">

            public XString()
            {}
            
//</code>
            
//<code id="properties" title="Length Property">

            public int Length
            {
            	get
            	{
            		return this.data.Length;
            	}
            }
            
//</code>
            
//<code id="methods" title="ToString Method">

            public override String ToString()
            {
            	return new String(this.data);
            }
            
//<code id="hashcode" title="GetHashCode">

            public override int GetHashCode()
            {
                return -1;
            }
            
//</code>
            
//</code>
            
//</code>
            }
            
}

Compilation results:

Language:CS
EntryPoint:True
Source Xml code:
<member name="T:NLiterate.Demo.HelloWorld"><summary>
            A simple example of literate documentation.
            </summary><remarks><code id="entry" entry-point="true" language="cs" compilable="true" hidden-namespace="Test">
            using System;
            
            public class HelloWorld
            {
                public static void Main()
                {
                    {[consoleout Testing console out here]}
                }
            }
            </code>
            blablab
            <code id="consoleout">
            Console.WriteLine("Hello world");
            </code></remarks></member>
MergedCode:
namespace Test
{

            using System;
            
            public class HelloWorld
            {
                public static void Main()
                {
                    
//<code id="consoleout" title="">

            Console.WriteLine("Hello world");
            
//</code>
                }
            }
            
}

Compilation results:
Execution results:
Success:
True
Return code:
-1
Console.Out:
Hello world

Console.Error:



By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Engineer
United States United States
Jonathan de Halleux is Civil Engineer in Applied Mathematics. He finished his PhD in 2004 in the rainy country of Belgium. After 2 years in the Common Language Runtime (i.e. .net), he is now working at Microsoft Research on Pex (http://research.microsoft.com/pex).

Comments and Discussions