Rainer Schuster

NamingMethod

Unter benanntem Thema gibt es in der Hilfe zum SHFB eine Beschreibung welche Möglichkeiten es zur Benennung der Indentifizierer gibt. Anders gesagt, welche Methode benutzt wird um die Namen für Verweise zu erzeugen. Die Themen, die aus den XML-Kommentaren erstellt werden speichert Sandcastle beim Buildprocess in eigenen HTML-Dateien. Der Name dieser Dateien richtet sich nach den in diesem Artikel genannten Möglichkeiten. Um die Hilfe zu generieren muss Sandcastle für die Verweise der Klassen und der vorliegenden Codestruktur entsprechende IDs erzeugen. Dazu gibt es im wesentlichen 3 Möglichkeiten.

1. GUID
2. MemberName
3. HashedMemberName

CodeSnippets

Die Berechnung der Topics kann durch folgende Snippets erzeugt werden (Auszug aus einer älteren SHFB-Hilfe)!

1. für GUID :

// Compute the MD5 hash of the member name.  Assume

// memberName contains the member name of the topic

// to show.

HashAlgorithm md5 = HashAlgorithm.Create("MD5");

byte[] input = Encoding.UTF8.GetBytes(memberName);

byte[] output = md5.ComputeHash(input);

// Format it as a GUID value

Guid pageId = new Guid(output);

// Show the topic in the help file.  Remember to add

// the "html\" folder name and the ".htm" extension.

Help.ShowHelp(parentForm, helpFilePath,

    HelpNavigator.Topic, @"html\" + pageId.ToString() + ".htm");

2. für MemberName:

Regex reInvalidChars = new Regex("[:.`#<>]");

// Assume memberName contains the member name of the

// topic to show.

string pageName = reInvalidChars.Replace(

    memberName, "_");

// Show the topic in the help file.  Remember to add

// the "html\" folder name and the ".htm" extension.

Help.ShowHelp(parentForm, helpFilePath,

    HelpNavigator.Topic, @"html\" + pageName + ".htm");

3. für HashedMemberName

// Assume memberName contains the member name of the

// topic to show.

string pageName = String.Format("{0:X}",

    memberName.GetHashCode());

// Show the topic in the help file.  Remember to add

// the "html\" folder name and the ".htm" extension.

Help.ShowHelp(parentForm, helpFilePath,

    HelpNavigator.Topic, @"html\" + pageName + ".htm");

Erklärung

Alle Hilfe-Themen besitzen ein Prefix um zu kennzeichnen welchen Bereichen sie zugeordnet sind. Diese sind nun wichtig. Deshalb hier besonderen Augenmerk darauf. Aus der Hilfe dazu hier der Auszug.

Note that each help topic ID will have a prefix denoting what it represents:

• R: represents the root namespace page. There will always be a single entry named R:Project.
• N: represents a namespace help topic that lists all of the members of the given namespace.
• T: represents a type help topic that lists all of the members of the given type.
• Overload: represents a help topic that lists all of the overloads for a particular class member.
• F: represents a field member.
• E: represents an event member.
• P: represents a property.
• M: represents a method.

Kritisch wird das bei tief verschachtelten Namesräumen bei den der Name zu lang wird. Dann sollte auf eine der anderen Möglichkeiten ausgewichen werden. Schwierig wird dann die eindeutige Referenzierung des z.B. gewünschten Members, da nur noch eine Kryptische ID vorhanden ist.

Welchen Vorteil bringt mir das noch aus eine schön strukturierte Hilfe? Wird eine Dokumentation für ein Windowsprogramm erstellt kann über den Hilfekontext mit der F1 Taste je nach gewählter Methode (siehe 1., 2., oder  3.) das Hilfethema referenziert werden.

Wer über den Index die Hilfe aufrufen will, muss einen anderen Member der HelpNavigator Enumeration aufrufen. Details dazu siehe MSDN