Jak: vytvoření komentářů dokumentace JavaScript XML

Článek
03/04/2013

Dokumentace komentáře XML jsou komentáře JavaScript Přidání skriptu poskytnout informace o kódu prvky jako například proměnných, funkcí a polí.V aplikaci Visual Studio jsou zobrazeny tyto textové popisy pomocí technologie IntelliSense při odkazu na funkci skriptu.

Toto téma obsahuje základní kurz pomocí komentářů dokumentace XML.Informace o použití jiných prvků, jako například <var> (JavaScript) a <value> (JavaScript)a příklady kódu naleznete v tématu Komentáře XML dokumentace (JavaScript).Informace o poskytnutí informace o technologii IntelliSense pro asynchronní zpětné volání jako Promise, viz <returns> (JavaScript).

[!POZNÁMKA]

Komentáře XML dokumentace jsou k dispozici pouze z odkazované soubory, sestavení a služby.

Vytvořit dokumentaci komentáře XML pro funkci jazyka JavaScript

Ve funkci Přidat <summary> (JavaScript), <param> (JavaScript), a <returns> (JavaScript) prvky a předcházet každý prvek s třemi lomítka (/ / /).

[!POZNÁMKA]

Každý prvek musí být na jednom řádku.

Následující příklad ukazuje funkci jazyka JavaScript.

  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;
  }

Chcete-li zobrazit komentáře XML dokumentace, zadejte název a levou závorku funkci, která je označena komentářů dokumentace XML jako v následujícím příkladu:
```
var areaVal = getArea(
```
Při psaní levou kulatou závorku pro funkci, která obsahuje dokumentaci komentáře XML Editor kódu používá k zobrazení informací, které je definováno v dokumentaci komentáře XML technologie IntelliSense.

Vytvoření poznámky dokumentace XML pro pole JavaScript

V definici funkce nebo objekt konstruktor přidat <field> (JavaScript) prvku předchází tři lomítka (/ / /).

Následující příklad ukazuje použití <field> prvku ve funkci konstruktoru.Další příklady naleznete v tématu <field> (JavaScript).
```
    function Engine() {
        /// <field name='HorsePower' type='Number'>The engine's horsepower.</field>
        this.HorsePower = 150;
    }
```
Chcete-li zobrazit komentáře XML dokumentace, vytvoření objektu pomocí funkce konstruktoru, která je označena komentářů dokumentace XML jako v následujícím příkladu.
```
    var eng = new Engine();
```
Na dalším řádku zadejte název objektu a období, které chcete zobrazit informace o technologii IntelliSense pro pole.
```
    eng.
```

Vytvořit dokumentaci komentáře XML pro přetížené funkce

Ve funkci Přidat <signature> (JavaScript) element pro každý přetížení.V těchto prvků přidat další prvky, například <summary>, <param>, a <returns>, předcházejících jednotlivých prvků tři lomítka (/ / /).

Následující příklad ukazuje přetížené funkce jazyka JavaScript.V tomto příkladu přetížení lišit podle typu parametru.

    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;
    }

Chcete-li zobrazit komentáře XML dokumentace, zadejte název a levou kulatou závorku pro funkci, která je označena komentářů dokumentace XML jako v následujícím příkladu:
```
    calc(
```

Vytvoření lokalizované IntelliSense

Vytvořte soubor XML obsahující komentáře k dokumentaci ve formátu OpenAjax MessageBundle.

Důležité

MessageBundle je doporučený formát.Tento formát nepodporuje Microsoft Ajax nebo .winmd soubory.Informace o použití alternativních VSDoc formát, viz <loc> (JavaScript).

Následující příklad ukazuje obsahu v souboru přívěsného vozíku, který obsahuje informace lokalizované technologie IntelliSense.Toto je soubor XML, který je umístěn ve složce specifické, stejně jako JA.Složka musí být ve stejném umístění jako soubor JS, který obsahuje <loc> prvku.Název souboru soubor XML musí odpovídat filename zadaný v parametru <loc> prvku.
```
<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>
```
Js souboru přidejte následující kód.<loc> Prvku musí být deklarován žádný skript před a následuje stejná pravidla využití jako <reference> prvku.Další informace naleznete v tématu JavaScript IntelliSense a <loc> (JavaScript).
```
/// <loc filename="messageFilename.xml" format="messagebundle"/>
```
Js souboru přidáte elementy XML dokumentace a popisy výchozí.Nastavit locid hodnoty odpovídajícího atributu name hodnoty atributu z něho souboru.Výchozí popis nahradí lokalizované informace IntelliSense, pokud je k dispozici.
```
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>
}
```
Chcete-li zobrazit komentáře XML dokumentace, zadejte název a levou závorku funkce jako v následujícím příkladu:
```
add(
```

Důležité
MessageBundle je doporučený formát.Tento formát nepodporuje Microsoft Ajax nebo .winmd soubory.Informace o použití alternativních VSDoc formát, viz <loc> (JavaScript).