valid - summary returns c#

¿Agregar descripciones de clase al código?

Question

Estoy terminando un proyecto en el que he estado trabajando durante un tiempo y solo estoy dando los toques finales.

Una cosa que me gustaría hacer es agregar descripciones de clase en la parte superior de cada archivo de clase (para ayudarme a mí mismo y a otros programadores a descubrir qué está pasando). Mi idea es usar solo un montón de ''/'' ''s para hacer una sección para que escriba algunas notas, pero ¿tal vez hay una mejor manera? ¿Hay una forma integrada de hacer esto en Visual Studio?

/////////////////////////////////////////////////////
//                                                 //
// KillZombies.cs                                  //
//                                                 //
// Description: This class contains blah blah blah //
//                                                 //  
/////////////////////////////////////////////////////

Answer 1

Los comentarios de documentación XML descritos en las respuestas anteriores son el camino a seguir para obtener documentación de clases y métodos.

Si necesita información adicional en cada archivo para el texto no documentado, como la fecha de creación, los créditos, los mensajes de derechos de autor, etc., puede agregarlo como un fragmento de código o agregarlo a la plantilla de Visual Studio correspondiente. VS tiene variables especiales para plantillas como $ username $ y $ time $ que se pueden usar para insertar automáticamente estos valores cada vez que agregue un nuevo elemento basado en su plantilla.

Answer 2

Sí, debes usar la documentación XML normal:

/// <summary>
/// Describe your class quickly here.
/// </summary>
/// <remarks>
/// Add more details here.
/// </remarks>

De esa manera, se mostrará en Intellisense, y si construye su documentación con Sandcastle / ndoc / Doxygen, etc., aparecerá correctamente.

Si escribe "///" en la línea sobre su clase, debería ver una plantilla apropiada para comenzar. Vea el enlace de MSDN arriba para más información.

Answer 3

Utilice comentarios de documentación XML :

/// <summary>
///  This class performs an important function.
/// </summary>

Cuando escribas las tres barras, Visual Studio te ayudará con el resto.

No use el elegante formato ASCII porque cuando se refactoriza para cambiar los nombres de las clases, pasará las edades reformateando todas las casillas para hacer que se alineen bien.