A veces la documentación tiende a repetirse, especialmente con Propiedades (para una persona que llama externa debe verse y sentirse como valores simples, por lo que es difícil ver cualquier punto al proporcionar entradas de 'resumen' y 'valor') .
Por lo tanto, trato de establecer una distinción entre el resumen y param/returns/value, etc., que reduce la repetitividad. El resumen describe brevemente lo que hace el método (calcular el conteo de widgets), mientras que el param/returns/value proporciona detalles de las entradas/salidas (y nada más). En muchos casos, verá una diferencia más marcada entre las entradas: al leer su ejemplo, inmediatamente tengo preguntas sobre la API que la documentación no responde, así que espero ver algo más como una de estas alternativas:
/// <summary>Recursively calculates the widget count for a given control.</summary>
///
/// <param name="control">The root control of the subtree to process, or null.</param>
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>
o ...
/// <summary>Calculates the widget count for a given control.</summary>
///
/// <param name="control">The control to process. May be null.</param>
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>
o incluso ...
/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param>
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is out of range.
/// </returns>
a diferencia de lo que @Bertie parece sugerir, siempre trato de reduzca la verbosidad y aumente el contenido de información - Como sabe lo que hace el método, puede que no necesite tantos detalles en la descripción del parámetro para describir para qué es, ya que a menudo es bastante obvio/intuitivo, pero lo hará A menudo, puede agregar más detalles sobre qué valores son legales o cómo se usa el parámetro, para ayudar al lector a entender la mejor manera de usarlo. De manera similar, para obtener detalles sobre el tipo de valor de retorno que obtendré (por ejemplo, si podría recuperar cero, valores negativos, nulos, etc.)
Considere que esta documentación define el contrato del código: cuanto más explícitamente declare el contrato, cuanto menos ambiguo sea y más fácil será que otro programador sepa cómo pueden (y no pueden) usar su método sin tener que leer el código fuente. O identifique si el comportamiento de su método es el deseado o un error. O sepa cuánto pueden alterar el comportamiento de su método sin romper ninguno de los códigos de llamadas existentes.
Por supuesto, en algunos casos, un método es realmente simple y lo suficientemente obvio como para comentarlo con AtomineerUtils y seguir adelante, ahorrando tiempo para trabajos más importantes. A menudo, la programación debe ser un equilibrio entre ser práctico (realizar el trabajo y enviar el producto) y cumplir con los ideales teóricos (DRY, etc.).
¿Por qué crees que la repetición en la documentación es tan mala? Desde el punto de vista del usuario, esto es algo bueno. Estoy de acuerdo en que adolece de mantenibilidad, pero de lo contrario ... – Oded
Generalmente, una diferencia a la que sirven los 'retornos' es proporcionar una representación textual del tipo. Tal como ' Un número entero que representa el conteo de widgets. ' –
Diría que su ejemplo es bastante acertado. En general, hay cierta repetición en la etiqueta. Si usa algo como GhostDoc, generará el 75% de los comentarios anteriores por usted con un clic en un botón (si su método se llama CalculateWidgetCount). –