¿Existen guías de estilo publicadas para la documentación de C# XML?

Question

Pido a mis desarrolladores que escriben código C# que sigan las pautas de StyleCop. Es genial para el código, pero casi siempre tengo preguntas sobre la documentación (vale ... vale ... así que nadie pregunta, porque los programadores tienden a odiar la documentación) estilo. Podría sugerir copiar el estilo de MSDN, pero tengo curiosidad de si Microsoft u otra persona ha publicado algo al respecto.

Por ejemplo, los constructores se documentan de la siguiente manera.

/// <summary> 
/// Initializes a new instance of <c>MyClass</c> using the specified <c>BaseMyClass</c>. 
/// </summary> 
/// <param name="myParam">The <c>MyParam</c> of the current session.</param> 

No estoy tratando de provocar un debate sobre cómo se debe escribir la documentación, aquí. Estoy buscando algún tipo de directrices publicadas sobre la sintaxis sugerida para la documentación.

¡Gracias de antemano!

Answer 1

StyleCop FxCop realmente proporciona reglas para la documentación de XML, también. Si no sigue el patrón establecido por un cierto conjunto de reglas, se quejará.

Estas son todas las reglas SA1600-SA1647.

Por ejemplo, SA1642 regla: ConstructorSummaryDocumentationMustBeginWithStandardText establece que:

El resumen para una instancia de constructor no privada debe comenzar con “Inicializa una nueva instancia de la {nombre de la clase} de clase.”

Para obtener más información, vea FxCop.

Answer 2

Si desea una guía general sobre cómo y dónde se debe usar la documentación XML, los siguientes son dos enlaces muy útiles (a los que me he referido en muchas ocasiones).

• MSDN Recommended Tags for Documentation Comments
• C# XML Documentation : Alan Dean (muertos - archived version)

Asumo que esto es vagamente el tipo de cosa que usted está buscando. Con respecto a la redacción y la gramática de los comentarios de XML, también busqué consejos/pautas sobre eso, pero fue en vano. La mejor idea a este respecto es simplemente seguir .NET BCL (Base Class Library), aunque existe una extraña incoherencia incluso en la documentación de BCL.

Espero que ayude ...

Answer 3

Mi estudio visual complemento, AtomineerUtils, generará y comentarios actualización xmlDoc.

Tiene un conjunto de plantillas que le permiten especificar el estilo exacto (qué entradas son legales para diferentes tipos de elemento de código, qué orden se enumeran, si hay líneas en blanco entre ciertas entradas, y el estilo del cerrando el bloque de documentación). Eliminará entradas que ya no son correctas (por ejemplo, eliminar parámetros) y agregará entradas para funciones no documentadas (por ejemplo, nuevos parámetros o excepciones lanzadas), y mantendrá la documentación ordenada mediante sangría automática y ajuste de palabras.

Así que al usar AU para generar y actualizar sus comentarios, puede aplicar fácilmente un estilo y diseño específico para los comentarios de su documentación.Si desea usar StyleCop para aplicar algunas reglas de documentación, AtomineerUtils tiene una opción para producir documentación en un formato compatible con StyleCop.

También hace que sea tan rápido y fácil documentar el código que incluso los programadores menos dispuestos en su equipo serán mucho más propensos a documentar bien su código.