visual valid net name generate example comment comentarios code c# vb.net visual-studio visual-studio-2008 xml-comments

c# - valid - ¿Cómo puedo hacer comentarios en IntelliSense para funcionar en Visual Studio?



summary param name c# (12)

En Visual Studio y C #, cuando se utiliza una función incorporada como ToString (), IntelliSense muestra un cuadro amarillo que explica lo que hace.

texto alternativo http://i44.tinypic.com/2r7rom8.jpg alt text http://i43.tinypic.com/5mcm4g.jpg

¿Cómo puedo tener eso para funciones y propiedades que escribo?

Además, el complemento visual studio ghost doc intentará crear y rellenar los comentarios del encabezado a partir del nombre de su función.

Defina métodos como este y obtendrá la ayuda que necesita.

/// <summary> /// Adds two numbers and returns the result /// </summary> /// <param name="first">first number to add</param> /// <param name="second">second number to </param> /// <returns></returns> private int Add(int first, int second) { return first + second; }

Captura de pantalla del uso del código

En CSharp, si crea el esquema de método / función con sus Parms, cuando agregue las tres barras diagonales, generará automáticamente la sección de resumen y parms.

Así que puse:

public string myMethod(string sImput1, int iInput2) { }

Luego puse los tres /// antes y Visual Studio me dio esto:

/// <summary> /// /// </summary> /// <param name="sImput1"></param> /// <param name="iInput2"></param> /// <returns></returns> public string myMethod(string sImput1, int iInput2) { }

Esos se llaman Comentarios XML . Han sido parte de Visual Studio desde siempre.

Puede facilitar su proceso de documentación utilizando GhostDoc , un complemento gratuito para Visual Studio que genera comentarios XML-doc por usted. Simplemente coloque su cursor sobre el método / propiedad que desea documentar, y presione Ctrl-Shift-D.

Aquí hay un ejemplo de una de mis publicaciones .

Espero que ayude :)

Haga comentarios XML, como este

/// <summary> /// This does something that is awesome /// </summary> public void doesSomethingAwesome() {}

Lo que necesita son comentarios XML , básicamente, siguen esta sintaxis (como Solmead describe vagamente):

DO#

///<summary> ///This is a description of my function. ///</summary> string myFunction() { return "blah"; }

VB

''''''<summary> ''''''This is a description of my function. ''''''</summary> Function myFunction() As String Return "blah" End Function

Solmead tiene la respuesta correcta. Para obtener más información, puede consultar los Comentarios XML .

Todas estas otras respuestas tienen sentido, pero están incompletas. Visual Studio procesará los comentarios de XML, pero debe activarlos. He aquí cómo hacerlo:

Intellisense utilizará los comentarios XML que ingrese en su código fuente, pero debe tenerlos habilitados a través de las Opciones de Visual Studio. Vaya a Tools > Options > Text Editor . Para Visual Basic, active Advanced > Generate XML documentation comments for '''''' configuración Generate XML documentation comments for '''''' . Para C #, active Advanced > Generate XML documentation comments for /// . Intellisense utilizará los comentarios resumidos cuando se ingrese. Estarán disponibles de otros proyectos después de compilar el proyecto al que se hace referencia.

Para crear documentación externa , debe generar un archivo XML a través de la Project Settings del Project Settings > Build > XML documentation file: ruta que controla la opción del compilador /doc . Necesitará una herramienta externa que tomará el archivo XML como entrada y generará la documentación en su elección de formatos de salida.

Tenga en cuenta que generar el archivo XML puede aumentar notablemente su tiempo de compilación.

use /// para comenzar cada línea del comentario y haga que el comentario contenga el xml apropiado para el lector de metadatos.

///<summary> /// this method says hello ///</summary> public void SayHello();

Aunque personalmente, creo que estos comentarios suelen ser erróneos, a menos que esté desarrollando clases donde el código no pueda ser leído por sus consumidores.

<c>text</c> - El texto que desea indicar como código.
La etiqueta < c > le permite indicar que el texto dentro de una descripción debe marcarse como código. Use < code > para indicar varias líneas como código.

<code>content</code> - El texto que desea marcar como código.
La etiqueta < code > le ofrece una forma de indicar varias líneas como código. Use < c > para indicar que el texto dentro de una descripción debe marcarse como código.

<example>description</example> - Una descripción de la muestra del código.
La etiqueta < ejemplo > le permite especificar un ejemplo de cómo usar un método u otro miembro de la biblioteca. Esto generalmente implica el uso de la etiqueta < code >.

<exception cref="member">description</exception> - Una descripción de la excepción.
La etiqueta < exception > le permite especificar qué excepciones se pueden lanzar. Esta etiqueta se puede aplicar a las definiciones de métodos, propiedades, eventos e indizadores.

<include file=''filename'' path=''tagpath[@name="id"]'' />
La etiqueta < include > le permite consultar comentarios en otro archivo que describen los tipos y miembros en su código fuente. Esta es una alternativa para colocar comentarios de documentación directamente en su archivo de código fuente. Al colocar la documentación en un archivo separado, puede aplicar el control de origen a la documentación por separado del código fuente. Una persona puede tener el archivo del código fuente desprotegido y alguien más puede tener el archivo de documentación desprotegido. La etiqueta < include > usa la sintaxis XML XPath. Consulte la documentación de XPath para conocer las formas de personalizar su uso de < include >.

<list type="bullet" | "number" | "table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item> </list>

El bloque < listheader > se usa para definir la fila del encabezado de una tabla o lista de definiciones. Al definir una tabla, solo necesita proporcionar una entrada para el término en el encabezado. Cada elemento en la lista se especifica con un bloque < item >. Al crear una lista de definiciones, deberá especificar tanto el término como la descripción. Sin embargo, para una tabla, una lista con viñetas o una lista numerada, solo necesita proporcionar una entrada para la descripción. Una lista o tabla puede tener tantos bloques de < item > como sea necesario.

<para>content</para>
La etiqueta < para > se usa dentro de una etiqueta, como < summary >, < remarks >, o < returns >, y le permite agregar estructura al texto.

<param name="name">description</param>
La etiqueta < param > se debe usar en el comentario de una declaración de método para describir uno de los parámetros del método. Para documentar múltiples parámetros, use múltiples etiquetas < param >.
El texto de la etiqueta < param > se mostrará en IntelliSense, el Examinador de objetos y en el Informe web de comentario de código.

<paramref name="name"/>
La etiqueta < paramref > le permite indicar que una palabra en los comentarios del código, por ejemplo, en un bloque < summary > o < remarks > se refiere a un parámetro. El archivo XML se puede procesar para formatear esta palabra de alguna manera distinta, como con una fuente en negrita o cursiva.

< permission cref="member">description</permission>
La etiqueta < permission > le permite documentar el acceso de un miembro. La clase PermissionSet le permite especificar el acceso a un miembro.

<remarks>description</remarks>
La etiqueta < observaciones > se usa para agregar información sobre un tipo, complementando la información especificada con < resumen >. Esta información se muestra en el Examinador de objetos.

<returns>description</returns>
La etiqueta < returns > se debe usar en el comentario para una declaración de método para describir el valor de retorno.

<see cref="member"/>
La etiqueta < see > le permite especificar un enlace desde dentro del texto. Use < seealso > para indicar que el texto debe colocarse en una sección Vea también. Use el atributo Cref para crear hipervínculos internos a páginas de documentación para elementos de código.

<seealso cref="member"/>
La etiqueta < seealso > le permite especificar el texto que tal vez desee que aparezca en una sección Vea también. Use < see > para especificar un enlace desde dentro del texto.

<summary>description</summary>
La etiqueta < summary > se debe usar para describir un tipo o un miembro de tipo. Use < observaciones > para agregar información suplementaria a una descripción de tipo. Utilice el atributo Cref para habilitar herramientas de documentación como Sandcastle para crear hipervínculos internos a páginas de documentación para elementos de código. El texto de la etiqueta < summary > es la única fuente de información sobre el tipo en IntelliSense, y también se muestra en el Examinador de objetos.

<typeparam name="name">description</typeparam>
La etiqueta < typeparam > se debe usar en el comentario para un tipo genérico o declaración de método para describir un parámetro de tipo. Agregue una etiqueta para cada parámetro de tipo del tipo o método genérico. El texto de la etiqueta < typeparam > se mostrará en IntelliSense, el informe web del comentario del código del navegador de objetos.

<typeparamref name="name"/>
Use esta etiqueta para permitir que los consumidores del archivo de documentación formateen la palabra de una manera distinta, por ejemplo en cursiva.

<value>property-description</value>
La etiqueta < value > le permite describir el valor que representa una propiedad. Tenga en cuenta que cuando agrega una propiedad mediante el asistente de código en el entorno de desarrollo Visual Studio .NET, agregará una etiqueta < summary > para la nueva propiedad. A continuación, debe agregar manualmente una etiqueta < value > para describir el valor que representa la propiedad.