Gewusst wie: Erstellen von JavaScript-XML-Dokumentationskommentaren

Artikel
06/10/2015

XML-Dokumentationskommentare sind JavaScript Kommentare, dass Sie ein Skript, um Informationen zu Code-Elemente, z. B. Variablen, Funktionen und Felder hinzufügen.In Visual Studio werden diese Textbeschreibungen mit IntelliSense angezeigt, wenn Sie die Skriptfunktion verweisen.

Dieses Thema enthält ein Lernprogramm zur Verwendung von XML-Dokumentationskommentare.Informationen über andere Elemente, z. B. <var> (JavaScript) und <value> (JavaScript), und Weitere Codebeispiele finden Sie unter XML-Dokumentationskommentare (JavaScript).Informationen zum Bereitstellen von IntelliSense Informationen für ein asynchroner Rückruf wie z. B. ein Promise, finden Sie unter <returns> (JavaScript).

Hinweis
XML-Dokumentationskommentare stehen nur aus referenzierten Dateien, Assemblys und Services zur Verfügung.

Erstellen von XML-Dokumentationskommentaren für eine JavaScript-Funktion

Fügen Sie in der Funktion <summary> (JavaScript), <param> (JavaScript), und <returns> (JavaScript) Elemente, und jedes Element mit drei Schrägstrichen (/ / /) vorausgehen.

Hinweis
Jedes Element muss in einer Zeile sein.

Das folgende Beispiel zeigt eine JavaScript-Funktion.

  function getArea(radius)
  {
      /// <summary>Determines the area of a circle that has the specified radius parameter.</summary>
      /// <param name="radius" type="Number">The radius of the circle.</param>
      /// <returns type="Number">The area.</returns>
      var areaVal;
      areaVal = Math.PI * radius * radius;
      return areaVal;
  }

Um die XML-Dokumentationskommentare anzuzeigen, geben Sie den Namen und die öffnende Klammer einer Funktion, die mit XML-Dokumentationskommentare, wie im folgenden Beispiel markiert ist:
```
var areaVal = getArea(
```
Wenn Sie die öffnende Klammer der Funktion, die die XML-Dokumentationskommentare enthält eingeben, verwendet der Code-Editor IntelliSense zum Anzeigen der Informationen, die in XML-Dokumentationskommentare definiert ist.

Erstellen von XML-Dokumentationskommentaren für eine JavaScript-Feld

Fügen Sie in einer Funktion oder das Objekt Konstruktordefinition, ein <field> (JavaScript) Element von drei Schrägstriche (/ / /) vorangestellt.

Das folgende Beispiel zeigt die Verwendung der <field> -Element in eine Konstruktorfunktion.Weitere Beispiele finden Sie unter <field> (JavaScript).
```
    function Engine() {
        /// <field name='HorsePower' type='Number'>The engine's horsepower.</field>
        this.HorsePower = 150;
    }
```
Um die XML-Dokumentationskommentare anzuzeigen, erstellen Sie ein Objekt mithilfe des Function-Konstruktors, der markiert ist mit XML-Dokumentationskommentaren, wie im folgenden Beispiel.
```
    var eng = new Engine();
```
Geben Sie den Namen des Objekts und einen Zeitraum IntelliSense Informationen für das Feld an, in der nächsten Zeile.
```
    eng.
```

Erstellen von XML-Dokumentationskommentaren für eine überladene Funktion

Fügen Sie in der Funktion einer <signature> (JavaScript) -Element für jede Überladung.Fügen Sie in diese Elemente andere Elemente, z. B. <summary>, <param>, und <returns>, jedes Element mit drei Schrägstrichen (/ / /) vor.

Das folgende Beispiel zeigt eine überladene JavaScript-Funktion.In diesem Beispiel unterscheiden sich die Überladungen von Parametertyp.

    function calc(a) {
        /// <signature>
        /// <summary>Function summary 1.</summary>
        /// <param name="a" type="Number">A number.</param>
        /// <returns type="Number" />
        /// </signature>
        /// <signature>
        /// <summary>Function summary 2.</summary>
        /// <param name="a" type="String">A string.</param>
        /// <returns type="Number" />
        /// </signature>
        return a;
    }

Um die XML-Dokumentationskommentare anzuzeigen, geben Sie den Namen und die öffnende Klammer, die Funktion, die mit XML-Dokumentationskommentare, wie im folgenden Beispiel markiert ist:
```
    calc(
```

Erstellen von lokalisierten IntelliSense

Erstellen Sie eine XML-Datei, die Dokumentationskommentare im Format OpenAjax MessageBundle hat.

Wichtig
MessageBundle ist das empfohlene Format.Dieses Format wird nicht in der Microsoft Ajax oder .winmd-Dateien unterstützt.Informationen zum Verwenden der Alternative VSDoc formatieren, finden Sie unter <loc> (JavaScript).

Das folgende Beispiel zeigt Inhalte in einem sogenannten Filialdokument, das die lokalisierte IntelliSense Informationen enthält.Dies ist eine XML-Datei, die in einem Ordner kulturspezifische wie JA befindet.Der Ordner muss sich in demselben Speicherort wie die js-Datei enthält die <loc> Element.Der Dateiname der XML-Datei muss übereinstimmen die filename Parameter angegeben wird, der <loc> Element.

<messagebundle>
  <msg name="1">A class that represents a rectangle</msg>
  <msg name="2">The length of the rectangle</msg>
  <msg name="3">The height of the rectangle</msg>
</messagebundle>

Fügen Sie den folgenden Code in der js-Datei.Die <loc> Element muss vor jedem Skript deklariert werden, und folgt denselben Verwendungsregeln als die <reference> Element.Weitere Informationen finden Sie unter JavaScript IntelliSense und <loc> (JavaScript).
```
/// <loc filename="messageFilename.xml" format="messagebundle"/>
```
In der js-Datei können fügen Sie die Elemente der XML-Dokumentation und Standard-Beschreibungen hinzu.Legen Sie die locid Attributwerte entsprechend den entsprechenden name Attributwerte aus der Datei Beiwagen.Lokalisierte IntelliSense Informationen ersetzt die Standard-Beschreibungen Wenn es verfügbar ist.
```
function add(a,b) 
{
    /// <summary locid='1'>description</summary>
    /// <param name='a' locid='2'>parameter a description</param>
    /// <param name='b' locid='3'>parameter b description</param>
}
```
Um die XML-Dokumentationskommentare anzuzeigen, geben Sie den Namen und die öffnende Klammer der Funktion, wie im folgenden Beispiel:
```
add(
```

Siehe auch

Konzepte

JavaScript IntelliSense

XML-Dokumentationskommentare (JavaScript)

Weitere Ressourcen

Exemplarische Vorgehensweise:: JavaScript IntelliSense in ASP.NET

Share via