Xml Dokumentation - Customizing?

29/10/2008 - 23:11 von Carsten Posingies | Report spam
Hallo NG,

nach viel Blut, Schweiß und Trànen habe ich mir ein Konzept für meine
eigenen Projekte zusammengestrickt, das aus den /doc-Erzeugnissen XHTML
bastelt (über XSLT). Dafür biege ich mir jedoch die "empfohlenen"
XmlDoc-Tags zurecht. Beispiel:

/// <param name="message" type="System.String">bla</param>

In der ursprünglichen Version enthàlt das Tag "param" kein Attribut
"type". Wenn man aber mal in die MSDN schaut, findet man stàndig:

Parameter:
/message/
Typ: System.String
bla

Genau sowas macht mein XSLT. Nur muss ich diese Zusatzattribute jedesmal
mit der Hand einhacken. Gibt es eine Möglichkeit, im Visual Studio 2008
die Erstellung von XmlDoc-Grundgerüsten zu erweitern? Beispiel:

public class MyException : Exception
{
// ...
public MyException(string message, Exception innerException) { /*
... */ }
}

Gehe ich nun also vor die erste Zeile des Konstruktors und tippe dreimal
"/" ein, erscheint:

/// <summary>
///
/// </summary>
/// <param name="message"></param>
/// <param name="innerException"></param>

Was ich gerne hàtte, wàre ganz speziell:

/// <summary>
/// <lang id="de">
///
/// </lang>
/// <lang id="en">
///
/// </lang>
/// </summary>
/// <param name="message" type="">
/// <lang id="de"></lang>
/// <lang id="en"></lang>
/// </param>
/// <param name="innerException" type="">
/// <lang id="de"></lang>
/// <lang id="en"></lang>
/// </param>

Das <lang>-Tag werte ich in meiner XSLT-Datei entsprechend aus, da ich
fast immer zweisprachig kommentiere. Deswegen geht es mir inzwischen
echt auf den Keks, den ganzen Kram für jede einzelne Methode hàndisch
einhacken zu müssen.

Das type-Attribut werte ich ebenfalls aus und beziehe es je nach
Namespace entweder auf den des .NET-Frameworks oder auf meinen eigenen.
Mir würde es schon reichen, dass, wie im Beispiel, wenigstens ein
Platzhalter automatisch erscheint.

Irgendjemand da draußen, der mir nen Tipp geben mag?

Danke!

Carsten
 

Lesen sie die antworten

#1 Frank Dzaebel
01/11/2008 - 17:33 | Warnen spam
Hallo Carsten,

nach viel Blut, Schweiß und Trànen habe ich mir ein Konzept für meine
eigenen Projekte zusammengestrickt, das aus den /doc-Erzeugnissen
XHTML bastelt (über XSLT). Dafür biege ich mir jedoch die
"empfohlenen" XmlDoc-Tags zurecht.



Du kennst Microsofts SandCastle und die ganzen Zusatz-Tools?
Hier mal ein Beispiel dafür, wie Profis ihre XML-Kommentare erstellen:

/// <include file='doc\Control.uex'
path='docs/doc[@for="Control.Controls"]/*' />
/// <devdoc>
/// Collection of child controls.
/// </devdoc>
[
Browsable(false),
DesignerSerializationVisibility(DesignerSerializationVisibility.Content),
SRDescription(SR.ControlControlsDescr)
]
public ControlCollection Controls
{
get
{
return [...];
}
}

__________________

Durch SRDescription ermöglicht übrigens die lokalisierte
Beschreibung innerhalb des Eigenschaften-Fensters.

[AttributeUsage(AttributeTargets.All)]
internal sealed class SRDescriptionAttribute : DescriptionAttribute
{...}

bei dem man über typsichere Ressourcen geht.


ciao Frank
Dipl.Inf. Frank Dzaebel [MCP/MVP C#]
http://Dzaebel.NET

Ähnliche fragen