/// <summary>
/// Checks declaration comment blocks.
/// </summary>
/// <param name="file">
/// The <see cref="ICSharpFile"/> to use.
/// </param>
/// <param name="declaration">
/// The <see cref="IDeclaration"/> to check.
/// </param>
/// <param name="options">
/// <see cref="OrderingOptions"/>Current options that we can reference.
/// </param>
public void CheckDeclarationDocumentation(ICSharpFile file, IDeclaration declaration, DocumentationOptions options)
{
Param.RequireNotNull(file, "file");
Param.RequireNotNull(declaration, "declaration");
Param.Ignore(options);
bool insertMissingElementDocOption = true;
bool documentationTextMustBeginWithACapitalLetter = true;
bool documentationTextMustEndWithAPeriod = true;
bool elementDocumentationMustHaveSummary = true;
bool constructorSummaryDocBeginsWithStandardText = true;
bool destructorSummaryDocBeginsWithStandardText = true;
bool propertyDocumentationMustHaveValueDocumented = true;
bool insertMissingParamTagOption = true;
bool genericTypeParametersMustBeDocumented = true;
if (options != null)
{
insertMissingElementDocOption = options.SA1600ElementsMustBeDocumented;
documentationTextMustBeginWithACapitalLetter = options.SA1628DocumentationTextMustBeginWithACapitalLetter;
documentationTextMustEndWithAPeriod = options.SA1629DocumentationTextMustEndWithAPeriod;
elementDocumentationMustHaveSummary = options.SA1604ElementDocumentationMustHaveSummary;
constructorSummaryDocBeginsWithStandardText = options.SA1642ConstructorSummaryDocumentationMustBeginWithStandardText;
destructorSummaryDocBeginsWithStandardText = options.SA1643DestructorSummaryDocumentationMustBeginWithStandardText;
propertyDocumentationMustHaveValueDocumented = options.SA1609PropertyDocumentationMustHaveValue;
insertMissingParamTagOption = options.SA1611ElementParametersMustBeDocumented;
genericTypeParametersMustBeDocumented = options.SA1618GenericTypeParametersMustBeDocumented;
}
DeclarationHeader declarationHeader = new DeclarationHeader(declaration);
bool formatSummary = false;
if (insertMissingElementDocOption && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1600) && declarationHeader.IsMissing)
{
formatSummary = this.InsertMissingDeclarationHeader(file, declaration);
}
if (elementDocumentationMustHaveSummary && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1604) && !declarationHeader.HasSummary)
{
formatSummary = formatSummary | this.InsertMissingSummaryElement(declaration);
}
if (formatSummary)
{
this.FormatSummaryElement(declaration);
}
if (declaration is IConstructorDeclaration)
{
if (insertMissingParamTagOption && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1611))
{
IConstructorDeclaration constructorDeclaration = declaration as IConstructorDeclaration;
if (constructorDeclaration.ParameterDeclarations.Count > 0)
{
this.InsertMissingParamElement(constructorDeclaration);
}
}
if (constructorSummaryDocBeginsWithStandardText && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1642))
{
this.EnsureConstructorSummaryDocBeginsWithStandardText(declaration as IConstructorDeclaration);
}
}
DocumentationRulesConfiguration docConfig = this.GetDocumentationRulesConfig(file);
// However it can be on/off depending on the file so we'd have to cache it per file
bool ruleIsEnabled = docConfig.GetStyleCopRuleEnabled("DocumentationTextMustBeginWithACapitalLetter");
if (documentationTextMustBeginWithACapitalLetter && ruleIsEnabled && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1628))
{
this.EnsureDocumentationTextIsUppercase(declaration);
}
ruleIsEnabled = docConfig.GetStyleCopRuleEnabled("DocumentationTextMustEndWithAPeriod");
if (documentationTextMustEndWithAPeriod && ruleIsEnabled && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1629))
{
this.EnsureDocumentationTextEndsWithAPeriod(declaration);
}
if (declaration is IDestructorDeclaration)
{
if (destructorSummaryDocBeginsWithStandardText && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1643))
{
this.EnsureDestructorSummaryDocBeginsWithStandardText(declaration as IDestructorDeclaration);
}
}
if (declaration is IMethodDeclaration || declaration is IIndexerDeclaration)
{
this.CheckMethodAndIndexerDeclarationDocumentation(declaration as IParametersOwnerDeclaration, options);
}
if (declaration is IPropertyDeclaration)
{
ruleIsEnabled = docConfig.GetStyleCopRuleEnabled("PropertyDocumentationMustHaveValue");
if (propertyDocumentationMustHaveValueDocumented && ruleIsEnabled && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1609))
{
this.InsertValueElement(declaration as IPropertyDeclaration);
}
}
if (declaration is ITypeParametersOwner && (genericTypeParametersMustBeDocumented && !Utils.IsRuleSuppressed(declaration, StyleCopRules.SA1618)))
{
this.InsertMissingTypeParamElement(declaration);
}
}
/// <summary>
/// Get default setting for given profile type.
/// </summary>
/// <param name="profile">
/// The code cleanup profile to use.
/// </param>
/// <param name="profileType">
/// Determine if it is a full or reformat <see cref="CodeCleanup.DefaultProfileType"/>.
/// </param>
public void SetDefaultSetting(CodeCleanupProfile profile, CodeCleanup.DefaultProfileType profileType)
{
// Default option are set in the constructors.
OrderingOptions orderingOptions = new OrderingOptions();
profile.SetSetting(OrderingDescriptor, orderingOptions);
LayoutOptions layoutOptions = new LayoutOptions();
profile.SetSetting(LayoutDescriptor, layoutOptions);
DocumentationOptions documentationOptions = new DocumentationOptions();
profile.SetSetting(DocumentationDescriptor, documentationOptions);
SpacingOptions spacingOptions = new SpacingOptions();
profile.SetSetting(SpacingDescriptor, spacingOptions);
ReadabilityOptions readabilityOptions = new ReadabilityOptions();
profile.SetSetting(ReadabilityDescriptor, readabilityOptions);
MaintainabilityOptions maintainabilityOptions = new MaintainabilityOptions();
profile.SetSetting(MaintainabilityDescriptor, maintainabilityOptions);
}
/// <summary>
/// Execute comments processing for declarations.
/// </summary>
/// <param name="options">
/// The <see cref="OrderingOptions"/> to use.
/// </param>
/// <param name="file">
/// The <see cref="ICSharpFile"/> to use.
/// </param>
public void Execute(DocumentationOptions options, ICSharpFile file)
{
StyleCopTrace.In(options, file);
Param.RequireNotNull(options, "options");
Param.RequireNotNull(file, "file");
foreach (ICSharpNamespaceDeclaration namespaceDeclaration in file.NamespaceDeclarations)
{
this.ProcessCSharpTypeDeclarations(options, file, namespaceDeclaration.TypeDeclarations);
}
this.ProcessCSharpTypeDeclarations(options, file, file.TypeDeclarations);
bool fixSingleLineCommentsOption = options.SA1626SingleLineCommentsMustNotUseDocumentationStyleSlashes;
if (fixSingleLineCommentsOption)
{
this.SwapDocCommentsToSingleLineComments(file.FirstChild);
}
this.UpdateFileHeader(options, file);
StyleCopTrace.Out();
}
/// <summary>
/// Inserts any missing items from the file header.
/// Also formats the existing header ensuring that the top and bottom line start with 2 slashes and a space and that a newline follows the header.
/// </summary>
/// <param name="options">
/// The options.
/// </param>
/// <param name="file">
/// The file to update.
/// </param>
private void UpdateFileHeader(DocumentationOptions options, ICSharpFile file)
{
// The idea here is to load the existing header into our FileHeader object
// The FileHeader object will ensure that the format of the header is correct even if we're not changing its contents
// Thus we'll swap it out if its changed at the end.
string fileName = file.GetSourceFile().ToProjectFile().Location.Name;
UpdateFileHeaderStyle updateFileHeaderOption = options.SA1633SA1641UpdateFileHeader;
if (updateFileHeaderOption == UpdateFileHeaderStyle.Ignore)
{
return;
}
DocumentationRulesConfiguration docConfig = this.GetDocumentationRulesConfig(file);
string summaryText = Utils.GetSummaryText(file);
FileHeader fileHeader = new FileHeader(file) { InsertSummary = options.SA1639FileHeaderMustHaveSummary };
switch (updateFileHeaderOption)
{
case UpdateFileHeaderStyle.ReplaceCopyrightElement:
fileHeader.FileName = fileName;
fileHeader.CompanyName = docConfig.CompanyName;
fileHeader.CopyrightText = docConfig.Copyright;
fileHeader.Summary = string.IsNullOrEmpty(fileHeader.Summary) ? summaryText : fileHeader.Summary;
break;
case UpdateFileHeaderStyle.ReplaceAll:
fileHeader.FileName = fileName;
fileHeader.CompanyName = docConfig.CompanyName;
fileHeader.CopyrightText = docConfig.Copyright;
fileHeader.Summary = summaryText;
break;
case UpdateFileHeaderStyle.InsertMissing:
fileHeader.FileName = string.IsNullOrEmpty(fileHeader.FileName) ? fileName : fileHeader.FileName;
fileHeader.CompanyName = string.IsNullOrEmpty(fileHeader.CompanyName) ? docConfig.CompanyName : fileHeader.CompanyName;
fileHeader.CopyrightText = string.IsNullOrEmpty(fileHeader.CopyrightText) ? docConfig.Copyright : fileHeader.CopyrightText;
fileHeader.Summary = string.IsNullOrEmpty(fileHeader.Summary) ? summaryText : fileHeader.Summary;
break;
}
fileHeader.Update();
}
/// <summary>
/// Process nested declarations.
/// </summary>
/// <param name="options">
/// <see cref="OrderingOptions"/>Current options that we can reference.
/// </param>
/// <param name="file">
/// The <see cref="ICSharpFile"/> to use.
/// </param>
/// <param name="typeDeclarations">
/// The type <see cref="ICSharpTypeDeclaration"/> to check.
/// </param>
private void ProcessNestedTypeDeclarations(DocumentationOptions options, ICSharpFile file, IEnumerable<ITypeDeclaration> typeDeclarations)
{
Param.RequireNotNull(options, "options");
Param.RequireNotNull(file, "file");
Param.RequireNotNull(typeDeclarations, "typeDeclarations");
foreach (ITypeDeclaration typeDeclaration in typeDeclarations)
{
this.CheckDeclarationDocumentation(file, typeDeclaration, options);
this.CheckClassDeclarationForParams(typeDeclaration, options);
foreach (ITypeMemberDeclaration memberDeclaration in typeDeclaration.MemberDeclarations)
{
this.CheckDeclarationDocumentation(file, memberDeclaration, options);
}
this.ProcessNestedTypeDeclarations(options, file, typeDeclaration.NestedTypeDeclarations);
}
}
/// <summary>
/// Checks method comment blocks.
/// </summary>
/// <param name="methodDeclaration">
/// The method <see cref="IDeclaration"/> to check.
/// </param>
/// <param name="options">
/// <see cref="OrderingOptions"/>Current options that we can reference.
/// </param>
private void CheckMethodAndIndexerDeclarationDocumentation(IParametersOwnerDeclaration methodDeclaration, DocumentationOptions options)
{
Param.Ignore(options);
if (methodDeclaration == null)
{
return;
}
bool insertMissingParamTagOption = true;
bool insertMissingReturnTagOption = true;
bool removeReturnTagOnVoidElementsOption = true;
if (options != null)
{
insertMissingParamTagOption = options.SA1611ElementParametersMustBeDocumented;
insertMissingReturnTagOption = options.SA1615ElementReturnValueMustBeDocumented;
removeReturnTagOnVoidElementsOption = options.SA1617VoidReturnValueMustNotBeDocumented;
}
if (insertMissingParamTagOption && !Utils.IsRuleSuppressed(methodDeclaration, StyleCopRules.SA1611))
{
if (methodDeclaration.ParameterDeclarations.Count > 0)
{
this.InsertMissingParamElement(methodDeclaration);
}
}
if (methodDeclaration.DeclaredElement == null)
{
return;
}
DeclaredTypeFromCLRName declaredTypeFromClrName = methodDeclaration.DeclaredParametersOwner.ReturnType as DeclaredTypeFromCLRName;
if (removeReturnTagOnVoidElementsOption && !Utils.IsRuleSuppressed(methodDeclaration, StyleCopRules.SA1617))
{
// Remove the <returns> if the return type is void
if (declaredTypeFromClrName != null && declaredTypeFromClrName.GetClrName().FullName == "System.Void")
{
this.RemoveReturnsElement(methodDeclaration as ITypeMemberDeclaration);
}
}
if (insertMissingReturnTagOption && !Utils.IsRuleSuppressed(methodDeclaration, StyleCopRules.SA1615))
{
// Insert the <returns> if the return type is not void and it was missing
if ((declaredTypeFromClrName != null && declaredTypeFromClrName.GetClrName().FullName != "System.Void") || declaredTypeFromClrName == null)
{
this.InsertReturnsElement(methodDeclaration as ITypeMemberDeclaration, Utils.GetXmlPresentableName(methodDeclaration.DeclaredParametersOwner.ReturnType));
}
}
}
/// <summary>
/// Checks a class comments block for parameters.
/// </summary>
/// <param name="typeDeclaration">
/// The <see cref="ITypeDeclaration"/> to check.
/// </param>
/// <param name="options">
/// <see cref="OrderingOptions"/>Current options that we can reference.
/// </param>
private void CheckClassDeclarationForParams(ITypeDeclaration typeDeclaration, DocumentationOptions options)
{
Param.RequireNotNull(typeDeclaration, "typeDeclaration");
Param.RequireNotNull(options, "options");
bool insertMissingParamTagOption = options.SA1611ElementParametersMustBeDocumented;
if (insertMissingParamTagOption)
{
if (typeDeclaration.DeclaredElement != null)
{
if (typeDeclaration.DeclaredElement.TypeParameters.Count > 0)
{
this.InsertMissingTypeParamElement(typeDeclaration);
}
}
}
}