¿Cómo tener comentarios en IntelliSense para la función en Visual Studio?

139

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

texto alternativo texto alternativo

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

Ali
fuente

Respuestas:

215

Para generar un área donde puede especificar una descripción para la función y cada parámetro para la función, escriba lo siguiente en la línea antes de su función y presione Enter:

  • C#: ///

  • VB: '''

Consulte Etiquetas recomendadas para comentarios de documentación (Guía de programación de C #) para obtener más información sobre el contenido estructurado que puede incluir en estos comentarios.

Solmead
fuente
2
Para enfatizar: Eso es triple barra en C ++ / C # (los comentarios normales son doble barra). Y en VB, son dos comillas simples, no una comilla doble.
abelenky
1
En realidad, son tres citas simples en vb
Joel Coehoorn
1
En realidad, en VB, son 3 comillas simples: '' '
hometoast
2
Como alternativa, en un archivo VB puede hacer clic derecho en una función o clase y hacer clic en "Insertar comentario". Para C #, puede usar StyleCop, que le pedirá que escriba buenos encabezados de documentación
usuario1069816
GhostDoc es una gran herramienta que puede agregar una gran cantidad de texto en los comentarios por usted. submain.com/products/ghostdoc.aspx
Karl Gjertsen
74

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

C#

///<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
Tomás Aschan
fuente
23

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

<code>content</code>- El texto que desea marcar como código.
La etiqueta < código > 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 del código de muestra.
La etiqueta < ejemplo > le permite especificar un ejemplo de cómo usar un método u otro miembro de la biblioteca. Esto comúnmente implica el uso de la etiqueta < código >.

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

<include file='filename' path='tagpath[@name="id"]' />
La etiqueta < include > le permite hacer referencia a comentarios en otro archivo que describen los tipos y miembros en su código fuente. Esta es una alternativa a 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 de código fuente desprotegido y otra persona 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 < 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 de encabezado de una tabla o lista de definición. Al definir una tabla, solo necesita proporcionar una entrada para el término en el encabezado. Cada elemento de 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, lista con viñetas o lista numerada, solo necesita proporcionar una entrada para la descripción. Una lista o tabla puede tener tantos bloques < item > como sea necesario.

<para>content</para>
La etiqueta < para > se usa dentro de una etiqueta, como < sumario >, < comentarios > o < retornos >, y le permite agregar estructura al texto.

<param name="name">description</param>
La etiqueta < param > debe usarse 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 Explorador de objetos y en el Informe web de comentarios de código.

<paramref name="name"/>
La etiqueta < paramref > le ofrece una forma de indicar que una palabra en el código comenta, 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 < permiso > permite documentar el acceso de un miembro. La clase PermissionSet le permite especificar el acceso a un miembro.

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

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

<see cref="member"/>
La etiqueta < ver > 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 quizás desee que aparezca en una sección Vea también. Use < ver > para especificar un enlace desde dentro del texto.

<summary>description</summary>
La etiqueta < summary > debe usarse para describir un tipo o un miembro de tipo. Use < comentarios > para agregar información complementaria a una descripción de tipo. Use 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 para la etiqueta < summary > es la única fuente de información sobre el tipo en IntelliSense, y también se muestra en el Explorador de objetos.

<typeparam name="name">description</typeparam>
La etiqueta < typeparam > debe usarse en el comentario para una declaración de tipo o método genérico 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 de comentarios del código del navegador de objetos.

<typeparamref name="name"/>
Use esta etiqueta para permitir a los consumidores del archivo de documentación formatear la palabra de alguna 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 de Visual Studio .NET, agregará una etiqueta < summary > para la nueva propiedad. Luego debe agregar manualmente una etiqueta < value > para describir el valor que representa la propiedad.

Max
fuente
11

Hacer comentarios XML, como este

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}
Michael Walts
fuente
66
Para parámetros agregue:///<param name="paramName">Tralala</param>
The Oddler
10

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 estar equivocados, a menos que esté desarrollando clases donde el código no pueda ser leído por sus consumidores.

En desarrolloChris
fuente
2
son buenos para recordatorios de accesos directos, o en cualquier lugar donde tenga un código de biblioteca donde tal vez el código sea legible pero se necesita un poco de trabajo adicional para llegar a él.
Joel Coehoorn
1
Estoy de acuerdo con usted en teoría, pero si usa ese ghostdoc, entonces está elevando la relación ruido / señal hasta el punto de que el resto de los comentarios son inútiles.
DevelopingChris
9

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 de documentos XML para usted. Simplemente coloque su cursor en el método / propiedad que desea documentar y presione Ctrl-Shift-D.

Aquí hay un ejemplo de una de mis publicaciones .

Espero que ayude :)

Igal Tabachnik
fuente
6

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

Entonces puse en:

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)
{
}
Semperfi89
fuente
6

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

Recev Yildiz
fuente
2

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

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

Para crear externa de documentación, es necesario generar un archivo XML a través de la Project Settings> Build> XML documentation file:camino que los controles del compilador /docopción. Necesitará una herramienta externa que tomará el archivo XML como entrada y generará la documentación en los formatos de salida que elija.

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

Suncat2000
fuente
1

Además, el documento fantasma del complemento de Visual Studio intentará crear y completar los comentarios del encabezado desde el nombre de su función.

Mark Rogers
fuente
0

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

Ed S.
fuente