TypeName | DocumentationTextMustMeetCharacterPercentage |
CheckId | SA1631 |
Category | Documentation Rules |
Cause
A section of the Xml header documentation for a C# element does not contain enough alphabetic characters.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs when part of the documentation does contain enough characters. This rule is calculated by counting the number of alphabetic characters and numbers within the documentation text, and comparing it against the number of symbols and other non-alphabetic characters. If the percentage of non-alphabetic characters is too high, this generally indicates poorly formatted documentation which will be difficult to read. For example, consider the follow summary documentation:
/// <summary>
/// @)$(*A name--------
/// </summary>
public class Name
{
...
}
How to Fix Violations
To fix a violation of this rule, rewrite the documentation text using grammatically proper language, and ensure that the ratio of symbols versus characters in the text is not too great.