Практическое руководство. Создание комментариев XML-документации для JavaScript

Статья
02/20/2013

Комментарии XML-документации , JavaScript комментарии добавить сценарий для предоставления сведений об элементах кода, такие как функции, поля и переменные.В Visual Studio эти текстовые описания отображаются с IntelliSense, при ссылке на функцию сценария.

Этот раздел предоставляет основные учебник по с помощью комментариев XML-документации.Дополнительные сведения об использовании других элементов, таких как <var> (JavaScript) и <value> (JavaScript)и Дополнительные примеры кода, см. Комментарии XML-документации (JavaScript).Сведения о предоставлении информации IntelliSense для асинхронного обратного вызова, таких как Promise, см. <returns> (JavaScript).

Примечание
Комментарии XML-документации, доступны только из файлов, сборок и служб.

Чтобы создать функцию JavaScript для комментариев XML-документации

Добавьте в функцию <summary> (JavaScript), <param> (JavaScript), и <returns> (JavaScript) элементы и предшествовать каждый элемент с тремя знаками косой черты (/ / /).

Примечание

Каждый элемент должен быть в одной строке.

Пример функции 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;
  }
```
Чтобы просмотреть комментарии XML-документации, введите имя и открывающую скобку функции, помеченные комментарии XML-документации, как показано в следующем примере:
```
var areaVal = getArea(
```
При вводе открывающей скобки функции, которая содержит комментарии XML-документации в редакторе кода используется IntelliSense для отображения сведений, определенных в комментарии XML-документации.

Примечание
Каждый элемент должен быть в одной строке.

Создавать комментарии XML-документации для поля JavaScript

Добавьте в конструктор объекта или функции определения <field> (JavaScript) элемент предшествует три косой черты (/ / /).

В следующем примере показано использование <field> элемент в функции конструктора.Дополнительные примеры см. в разделе <field> (JavaScript).
```
    function Engine() {
        /// <field name='HorsePower' type='Number'>The engine's horsepower.</field>
        this.HorsePower = 150;
    }
```
Чтобы просмотреть комментарии XML-документации, следует создайте объект с помощью функции конструктора, помеченного с комментариями документации XML, как показано в следующем примере.
```
    var eng = new Engine();
```
В следующей строке введите имя объекта и отображать сведения о IntelliSense в поле период.
```
    eng.
```

Создавать комментарии XML-документации для перегруженной функции

Добавьте в функцию <signature> (JavaScript) элемента для каждой перегрузки.В этих элементах добавлять другие элементы, такие как <summary>, <param>, и <returns>, предшествующего каждый элемент с тремя косой черты (/ / /).

В следующем примере показано перегруженной функции JavaScript.В этом примере перегрузки отличаются по типу параметра.
```
    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;
    }
```
Чтобы просмотреть комментарии XML-документации, введите имя и открывающую скобку функции, помеченные комментарии XML-документации, как показано в следующем примере:
```
    calc(
```

Для создания локализованных IntelliSense

Создайте XML-файл, содержащий комментарии документации в формате MessageBundle альянсе.

Важно
MessageBundle — это рекомендуемый формат.Этот формат не поддерживается в Microsoft Ajax или в файлах .winmd.Дополнительные сведения об использовании вместо VSDoc формат, см. <loc> (JavaScript).

В следующем примере показано содержимое в сопроводительным файлом, содержащий локализованные сведения IntelliSense.Это XML-файл, который находится в папке определенного языка и региональных параметров, например JA.Папка должна находиться в той же папке, как JS-файла, который содержит <loc> элемент.Имя файла XML-файл должен соответствовать filename параметр, указанный в <loc> элемент.

<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-файла добавьте следующий код.<loc> Элемент должен быть объявлен перед любым сценарием и следует тем же правилам использования как <reference> элемент.Дополнительные сведения см. в разделах IntelliSense для JavaScript и <loc> (JavaScript).
```
/// <loc filename="messageFilename.xml" format="messagebundle"/>
```
В JS-файла добавьте XML-документации элементов и описания по умолчанию.Установка locid значения в соответствии с соответствующих атрибутов name значения атрибутов с сопроводительным файлом.Описание по умолчанию будут заменены локализованные сведения IntelliSense, если он доступен.
```
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>
}
```
Чтобы просмотреть комментарии XML-документации, введите имя и открывающую скобку функции, как показано в следующем примере:
```
add(
```

См. также

Основные понятия

IntelliSense для JavaScript

Комментарии XML-документации (JavaScript)

Другие ресурсы

Пошаговое руководство. IntelliSense для JavaScript в ASP.NET

Поделиться через