Cómo: Crear comentarios de documentación XML de JavaScript

Artículo
06/10/2015

Comentarios de documentación XML son los comentarios de JavaScript que agregar a una secuencia de comandos para proporcionar información acerca de los elementos de código, como las funciones, campos y las variables.En Visual Studio, estas descripciones de texto se muestran con IntelliSense cuando se hace referencia la función de secuencia de comandos.

Este tema proporciona un tutorial básico sobre el uso de comentarios de documentación XML.Para obtener información acerca de cómo utilizar otros elementos, tales como <var> (JavaScript) y <value> (JavaScript)y para obtener ejemplos de código adicional, consulte Comentarios de documentación XML (JavaScript).Para obtener información acerca de cómo proporcionar información de IntelliSense de devolución de llamada asincrónica, como un Promise, consulte <returns> (JavaScript).

[!NOTA]

Comentarios de documentación XML están disponibles sólo en los servicios, los ensamblados y archivos que se hace referencia.

Para crear comentarios de documentación XML para una función de JavaScript

En la función, agregue <summary> (JavaScript), <param> (JavaScript), y <returns> (JavaScript) elementos y delante de cada elemento con tres signos de barra diagonal (/ / /).

[!NOTA]

Cada elemento debe estar en una sola línea.

En el ejemplo siguiente se muestra una función de 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;
  }

Para ver los comentarios de documentación XML, escriba el nombre y el paréntesis de apertura de una función marcada con comentarios de documentación XML, como en el ejemplo siguiente:
```
var areaVal = getArea(
```
Al escribir el paréntesis de apertura de la función que contiene los comentarios de documentación XML, en el Editor de código se utiliza IntelliSense para mostrar la información que se define en los comentarios de documentación XML.

Para crear comentarios de documentación XML para un campo de JavaScript

En una definición de objeto o función de constructor, agregue un <field> (JavaScript) elemento precedidos por tres signos de barra diagonal (/ / /).

En el ejemplo siguiente se muestra el uso de la <field> elemento de una función constructora.Para obtener otros ejemplos, vea <field> (JavaScript).
```
    function Engine() {
        /// <field name='HorsePower' type='Number'>The engine's horsepower.</field>
        this.HorsePower = 150;
    }
```
Para ver los comentarios de documentación XML, crear un objeto con el constructor de la función que está marcado con comentarios de documentación XML, como en el ejemplo siguiente.
```
    var eng = new Engine();
```
En la siguiente línea, escriba el nombre del objeto y un período para mostrar la información de IntelliSense para el campo.
```
    eng.
```

Para crear comentarios de documentación XML para una función sobrecargada

En la función, agregue un <signature> (JavaScript) (elemento) para cada sobrecarga.En estos elementos, agregar otros elementos, tales como <summary>, <param>, y <returns>, anterior a cada elemento con tres diagonales (/ / /).

En el ejemplo siguiente se muestra una función sobrecargada de JavaScript.En este ejemplo, las sobrecargas se diferencian por el tipo de parámetro.

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

Para ver los comentarios de documentación XML, escriba el nombre y el paréntesis de apertura de la función que está marcada con comentarios de documentación XML, como en el ejemplo siguiente:
```
    calc(
```

Para crear IntelliSense localizada

Crear un archivo XML que tiene comentarios de documentación en el formato de OpenAjax MessageBundle.

Importante
MessageBundle es el formato recomendado.Este formato no es compatible con Ajax de Microsoft o en los archivos de .winmd.Para obtener información acerca del uso de la alternativas VSDoc de formato, vea <loc> (JavaScript).

En el ejemplo siguiente se muestra contenido en un archivo sidecar que contiene la información de IntelliSense localizada.Se trata de un archivo XML que se encuentra en una carpeta específica de la referencia cultural, como JA.La carpeta debe estar en la misma ubicación que el archivo .js que contiene el <loc> elemento.El nombre de archivo del archivo XML debe coincidir con el filename parámetro especificado en la <loc> elemento.

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

En el archivo .js, agregue el código siguiente.El <loc> elemento se debe declarar antes de cualquier secuencia de comandos y sigue las mismas reglas de uso como la <reference> elemento.Para obtener más información, vea IntelliSense para JavaScript y <loc> (JavaScript).
```
/// <loc filename="messageFilename.xml" format="messagebundle"/>
```
En el archivo .js, agregue los elementos de documentación XML y las descripciones de predeterminado.Establecer el locid valores para que coincida con el correspondiente del atributo name los valores de atributo del archivo sidecar.Las descripciones de predeterminado se reemplazará por información localizada de IntelliSense, si está disponible.
```
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>
}
```
Para ver los comentarios de documentación XML, escriba el nombre y el paréntesis de apertura de la función, como en el ejemplo siguiente:
```
add(
```

Vea también

Conceptos

IntelliSense para JavaScript

Comentarios de documentación XML (JavaScript)

Otros recursos

Tutorial: IntelliSense JavaScript en ASP.NET

Compartir a través de