Syntax Generation

  • Article

Syntax in Sandcastle documentation is generated by SyntaxBuilder. SyntaxBuilder uses the Common Compiler Infrastructure (CCI) library to reflect over a set of managed assemblies and produce syntax blocks that represent each API in various languages. SyntaxBuilder was developed during VS2005 ship cycle.

In principle, the information required to generate syntax blocks is contained in the reflection data produced by MRefBuilder, so a separate reflection step is not strictly necessary. However, two strong arguments have convinced us to nevertheless keep this step. First, the SytnaxBuilder code base exists and does its job well; using XML data as input instead of CCI objects would require a near-complete re-write. Second, the logic involved in generating syntax blocks can be quite complex and require referencing obscure pieces of reflection data; using CCI objects guarantees that all the information in an assembly, up to an including individual IL instructions, is available to generate syntax.

SyntaxBuilder is extensible in two ways: users can define SyntaxWriters, which define an output format, or SyntaxGenerators, which define a syntax block. We will provide three SyntaxWriters:

  • UscSyntaxWriter (generates a shared content file for use by pDoc in the previous version of Sandcastle)

  • HtmlSyntaxWriter (generates HTML for direct viewing)

  • XmlSyntaxWriter (generates an XML file for use by the new toolset)

Sandcastle will provide seven SyntaxGenerators:

  • C# Declaration Syntax

  • Visual Basic Declaration Syntax

  • Managed C++ Declaration Syntax

  • J# Declaration Syntax

  • Jscript Declaration Syntax

  • Visual Basic Usage Syntax

  • XAML Usage Syntax

The abstract SyntaxWriter class is defined as follows:

public abstract class SyntaxWriter : IDisposable {

protected SyntaxWriter (TextWriter writer) {}

          public abstract void WriteStartDocument ();

          public abstract void WriteStartApi (string id);

          public abstract void WriteStartBlock (string name);

          public abstract void WriteString (string text);

public abstract void WriteStringWithStyle (string text, string style);

          public virtual void WriteIdentifier (string identifier) {}

          public virtual void WriteKeyword (string keyword) {}

          public virtual void WriteParameter (string parameter) {}

          public virtual void WriteMessage (string message) {}

          public abstract void WriteReference (string reference);

          public abstract void WriteReference (string reference, string display);

          public abstract void WriteEndBlock ();

          public abstract void WriteEndApi ();

          public abstract void WriteEndDocument ();

          public virtual void Dispose ();

}

The abstract SyntaxGenerator class is defined as follows:

public abstract class SyntaxGenerator {

          public abstract void WriteSyntax (Member api, SyntaxWriter writer);

          protected ApiFilter ApiFilter { get; }

          protected AttributeFilter AttributeFilter { get; }

}

Sandcastle.config file has the following structure for syntax generation:

<!-- Generate syntax -->

          <component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll">

          <if condition="not(starts-with($key,'Overload:') or starts-with($key,'R:'))" />

          <then>

          <component type="Microsoft.Ddue.Tools.SyntaxComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll">

<syntax input="/document/reference" output="/document/syntax" />

<generators>

              <generator type="Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator" assembly="..\..\ProductionTools\BuildComponents\SyntaxGenerators.dll" />

              <generator type="Microsoft.Ddue.Tools.VisualBasicDeclarationSyntaxGenerator" assembly="..\..\ProductionTools\BuildComponents\SyntaxGenerators.dll" />

              <generator type="Microsoft.Ddue.Tools.CPlusPlusDeclarationSyntaxGenerator" assembly="..\..\ProductionTools\BuildComponents\SyntaxGenerators.dll" />

            </generators>

          </component>

          </then>

          </component>

 

Sandcastle users can provide custom syntax generators at the <generator /> section.