Sandcastle

Sandcastle-Dokumentationen sind generierter und strukturierte Content, welche als HTML-Content oder als Hilfedatei (z.B. CHM-Datei) ausgegeben werden. 

• Auflistung der Namespaces.
• Startseite des Namespace enthält
  • Auflistung der Klassen (Classes),
  • Enumerationen (Enumerations) und
  • Schnittstellen (Interfaces)
• Klasse besteht aus
  • Startseite mit zentralen Informationen zur Klasse (Class Example)
    • Klassenzusammenfassung,
    • Gesamtsyntax (Attribute)
    • Vererbungshieraschie
  • Mitgliedern (Members, All Members of Example):
    • Konstruktoren,
    • Methoden,
    • Eigenschaften,
    • Felder
    • Ereignisse
• Methoden (Method Example) und Konstruktoren
  • Beschreibung
  • Gesamtsyntax (Attribute)
  • Parameterbeschreibung
  • Rückgabewertbeschreibung
• Eigenschaften und Felder
  • Beschreibung
  • Gesamtsyntax

Im Kopfteil der Seiten sind mitunter die folgenden Links zu finden:

• Members (Mitglieder-Auflistung einer Klasse)
• Example Class (Zentralseite der Klasse)
• Namespace: Example (Startseite des Namespace)

Im Fußteil der Seiten finden Sie den Abschnitt See Also mit Links zu:

• Example Members (Mitglieder-Auflistung einer Klasse)
• Example Class (Zentralseite einer Klasse)
• Example Namespace (Startseite des Namespace)
• Overview of Namespaces (Übersicht mehrere Namespace)

http://sandcastle.codeplex.com/

Vorbereitung der Klassenbibliothek-Assembly

• Erstellung der Quellcodekommentierung für öffentliche (public) oder geschützte (protected, override) Klassen, Methoden, Eigenschaften, Felder, Enums/ Enum-Optionen mit ///, siehe Hinweise unten
• Ausgabe der Dokumentationsdatei (.xml) aktivieren in Projekteigenschaften > Erstellen.

Für die Erstellung des Sandcastle-Projektes werden die Assembly (dll) selbst und die Dokumentationsdatei (xml) benötigt.

Erstellen eines Sandcastle-Projektes

Zuerst erstellt man ein Sandcastle-Projekt (*.scproj). Mit einem Sandcastle-Projekt wird der Generierungablauf konfiguriert, der zur Laufzeit durch MSBuild.exe ausgeführt wird. Mit entsprechendem Hintergrundwissen kann man die Projektdatei im Texteditor bearbeiten. Die Erstellung geht auch mit dem mitgeliefertem GUI. 

• GUI SandcastleGui.exe starten
• Assembly auswählen (test.dll)
• Comments auwählen (XML-Datei sandcastle/comments.xml)
• Chm-Ausgabe einschlaten,
• Web-Ausgabe nicht einschalten (gunktioniert nicht, siehe unten)
• Projekt speichen

Neben diesem Projektfile ist eine weitere Datei Generic.targets wichtig, welche von dem Projektfile eingebunden wird. Die befindet sich im Sandcastle-Installationsverzeichnis: C:\Program Files\Sandcastle\Examples\generic

Hier ist unter anderem das Ausgabeverzeichnis BuildDir konfiguriert, welches einmalig geändert werden sollte, wenn die Ausgaben nicht unterhalb des Programmverzeichnis erfolgen soll: 

< BuildDir>C:\Users\***\_net\Doc\$(Name)< /BuildDir>

Der Projektname wird im Projektfile bzw. im GUI eingegeben. Nur gibt es mit dieser Variante ein Problem, wenn der Projektname einen Punkt enthält. Alternativ kann dann das Ausgabeverzeichnis auch in TopicStyleDir konfiguriert: 

< TopicStyleDir>C:\Users\***\_net\Doc\$(TopicStyle)< /TopicStyleDir>

Alle weiteren Einträge, z.B. OutputDir nicht verändern

Ausführen eines Sandcastle-Projektes

• Build im GUI klicken
• sehr elementar: build_Sandcastle.bat vs2005 test (erstellt aber nur eine Assembly)
• mit MSBuild.exe

Unter älteren Windowsversionen (Windows 2000) funktionierte das GUI nicht, aber MSBuild und die Sandcastle-Werkzeuge funktionieren. MSBuild.exe befindet sich unter: C:\Windows\Microsoft.NET\Framework\v2.0.50727\MSBuild.exe. Möglicherweise ist die Variable DXROOT nicht definiert, welche in dem Projektfile verwendet wird. Ohne die werden die Programme unter ProductionTools nicht gefunden. Es ist daher sinnvoll ein *.cmd wie folgt zu erstellen:

set DXROOT=c:\Programme\Sandcastle
C:\Windows\Microsoft.NET\Framework\v2.0.50727\MSBuild.exe Sandcastle.scproj

Um ferner ein systemübergreifende Funktion der *.scproj zu ermöglichen, müssen die absoluten Pfade aus der *.scproj entfernt werden, die vom GUI erstellt wurden. Danach kann die Datei mit dem GUI möglicherweise nicht mehr bearbeitet werden, was aber nicht so schlimm ist. Die Datei sieht dann so aus:

< ?xml version="1.0" encoding="utf-8"?>
< Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="Chm">
    < PropertyGroup>
        < Name>NsoftHis< /Name>
        < TopicStyle>vs2005< /TopicStyle>
        < LanguageId>1033< /LanguageId>
    < /PropertyGroup>
    < ItemGroup>
        < Dlls Include="Nsoft.DataAccess.Interface.dll" />
        < Dlls Include="Nsoft.Sys.Interfaces.dll" />
        < Comments Include="Nsoft.DataAccess.Interface.xml" />
        < Comments Include="Nsoft.Sys.Interfaces.xml" />
        < Dependents Include=".\*.*" />
    < /ItemGroup>
    < Import Project="$(DXROOT)\Examples\Generic\generic.targets" />
< /Project>

Es ist dann auch möglich die Projektdatei in das Release-Verzeichnis zu befördern.

Unter älteren Windowsversionen muss beachtet werden, dass die zu verarbeitende Assembly ausschließlich auf dem auf dem Build-System verfügberem Framework basiert. (Bei Windows 2000 wird nur Framework 2.0 unterstützt). Maßgebend dafür sind die Referenzen in den Assemblies (*.dll). Referenzen auf nicht unterstützte Framework-Assmeblies (z.B. System.Runtime.Serialization 3.0) dürfen dann nicht enthalten sein.

• Manchmal Fehlermeldung und Abbruch wegen nicht auflösbarer Abhängigkeiten
• Wie kann man einen index für alle Namespaces erzeugen
• Web-Ziel geht nicht

Web-Ziel

Man kann Html erzeugen über das Chm-Ziel, aber Ziel Web geht nicht, wodurch eine Website nicht erstellt wird.

• Beim Erstellen des Web-Ziels scheitert der Aufruf von XslTransform.exe, weil offenbar die Datei ...\output\TopicInfo\*.xml fehlt
• Es wird auch CreateWebDirs nicht ausgeführt
• Ursache ist vermutlich Fehlen von ...\Sandcastle\Examples\Generic\vs2005-web.config

http://social.msdn.microsoft.com/Forums/en/devdocs/thread/b4e8fa38-9471-4c61-a3b2-c784ea367dfa

Wir haben für die Webveröffentlichung eine andere Variante gefunden. Wir haben für CELLstudio eine Extension programmiert, mit der wir die html-Dateien darstellen. Die Extension filtert außerdem die HTML und entfernt nicht erwünschte Bestandteile. Außerdem haben wir JavaScript-Interaktion rausgenommen, eigene Styles erzeugt und Programmiersprachen deaktiviert.

Hinweise zur Erstellung der Kommentare

• /// eingeben vor Klassen, Methoden, Eigenschaften, nicht erforderlich bei private
• Bei der Erstellung hift IntelliSense, tippen sie < .
• Klasse
  • es empfiehlt sich einen Block < summary> zu erstellen, wird als Zusammenfassung in der Namespace-Übersicht angezeigt.
  • darunter den Block < remarks> erstellen, wird in der Klassenbeschreibung angezeigt
• Members
  • < summary> dürfte ausreichend sein
• Fehlende oder falsch strukturierte Dokumentationselemente werden in der Enwicklungsumgebung markiert und als Warnung ausgegeben

Tags

• summary,
  • c,
  • list, item,
  • para
• remarks
• note
• param
• preliminary
• overloads
• example, code
• permissions
• exceptions

Beispiel Code

using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Runtime.Serialization; 
 
namespace TestNamespace 
{
/// < summary>
/// Tests whether sandcastle can handle all c# tags as defined 
/// at http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx.
/// Comments of method "Increment (int step)" include almost all tags.
/// Method "Swap" is used to test generics tags, such as "typeparam".
/// < threadsafety static="true" instance="false"/>
/// < /summary>
[Serializable()] 
public class StoredNumber
{
  /// < summary>Initializes the stored number class with a starting value.< /summary>
  public StoredNumber(int value) 
  {
    number = value;
  }
 


  private int number;
 
  /// < preliminary>
  /// < para>This method is just for testing right now. It might be removed in the near future< /para>
  /// < /preliminary>
  public void PreliminaryTest() 
  {
  }
 
  /// < overloads>
  /// < summary>test overlads tag< /summary>
  /// < /overloads>
  public void Dec() 
  {
    number--;
  }
 
  /// < summary>
  /// dec by a specified step
  /// < /summary>
  /// < param name="step">< /param>
  public void Dec(int step) 
  {
    number -= step;
  }

 
  /// < summary>< c>Increment< /c> method incriments the stored number by one. 
  /// < note type="caution">
  /// note description here
  ///< /note>
  /// < preliminary/>
  /// < /summary> 
  public void Increment() 
  {
    number++;
  }
 
  /// < summary>< c>Increment< /c> method incriments the stored number by a specified < paramref name="step"/>. 
  /// < list type="number">
  /// < item>
  /// < description>Item 1.< /description>
  /// < /item>
  /// < item>
  /// < description>Item 2.< /description>
  /// < /item>
  /// < /list>
  /// < para>see < see cref="System.Int32"/>< /para>
  /// < para>seealso < seealso cref="System.Int64"/>< /para>
  /// < /summary> 
  /// < remarks>
  /// You may have some additional information about this class.
  /// < /remarks>
  /// < example> This sample shows how to call the GetZero method.
  /// < code>
  /// class TestClass 
  /// {
  ///   static int Main() 
  ///   {
  ///     return GetZero();
  ///   }
  /// }
  /// < /code>
  /// < /example>
  ///
  /// < exception cref="System.Exception">Thrown when...< /exception>
  /// < param name="step"> specified step< /param>
  /// < permission cref="System.Security.PermissionSet">Everyone can access this method.< /permission>
  /// < returns>Returns nothing< /returns>
  /// < value>The Name property gets/sets the _name data member.< /value>
  public void Increment(int step) 
  {
    number = number + step;
  }
 
  /// < summary>
  /// Swap data of type < typeparamref name="T"/>
  /// < /summary>
  /// < param name="lhs">left < typeparamref name="T"/> to swap< /param>
  /// < param name="rhs">right < typeparamref name="T"/> to swap< /param>
  /// < typeparam name="T">The element type to swap< /typeparam>
  public void Swap< T>(ref T lhs, ref T rhs) 
  {
    T temp;
    temp = lhs;
    lhs = rhs;
    rhs = temp;
  }
  

  /// < summary>Gets the stored number.< /summary>
  public int Value 
  {
    get
    {
      return (number); 
    }
  }
 
  private int _myProp; 
 
  ///< summary>
  ///see < see langword="null"/> as reference
  ///< /summary>
  public int MyProp 
  {
    get { return _myProp; }set { _myProp = value; } 
  }

}

}