/// <summary>
/// Creates a new DeclarationHeader for the declaration and assigns it to the declaration.
/// </summary>
/// <param name="declaration">
/// The declaration to create the header for.
/// </param>
/// <param name="docConfig">
/// Provides the configuration for the current ProjectFile.
/// </param>
/// <returns>
/// A DeclarationHeader for the declaration passed in.
/// </returns>
public static DeclarationHeader CreateNewHeader(IDeclaration declaration, DocumentationRulesConfiguration docConfig)
{
IFile file = declaration.GetContainingFile();
using (WriteLockCookie.Create(file.IsPhysical()))
{
IDeclaration declarationTreeNode = declaration;
IContextBoundSettingsStore settingsStore = PsiSourceFileExtensions.GetSettingsStore(null, declaration.GetSolution());
bool useSingleLineDeclarationComments = settingsStore.GetValue((StyleCopOptionsSettingsKey key) => key.UseSingleLineDeclarationComments);
string middleText = useSingleLineDeclarationComments ? string.Empty : Environment.NewLine;
string emptyDocHeader = string.Format("<summary>{0}</summary>", middleText);
if (!(declarationTreeNode is IMultipleDeclarationMember))
{
emptyDocHeader = CreateDocumentationForElement((IDocCommentBlockOwnerNode)declaration, docConfig);
emptyDocHeader = emptyDocHeader.Substring(0, emptyDocHeader.Length - Environment.NewLine.Length);
}
string header = LayoutDocumentationHeader(emptyDocHeader, declaration);
IDocCommentBlockNode newDocCommentNode = Utils.CreateDocCommentBlockNode(file, header);
IDocCommentBlockOwnerNode docCommentBlockOwnerNode = Utils.GetDocCommentBlockOwnerNodeForDeclaration(declaration);
if (docCommentBlockOwnerNode != null)
{
docCommentBlockOwnerNode.SetDocCommentBlockNode(newDocCommentNode);
}
return(new DeclarationHeader(declaration));
}
}
/// <summary>
/// Creates a new DeclarationHeader for the declaration and assigns it to the declaration.
/// </summary>
/// <param name="declaration">
/// The declaration to create the header for.
/// </param>
/// <param name="docConfig">
/// Provides the configuration for the current ProjectFile.
/// </param>
/// <returns>
/// A DeclarationHeader for the declaration passed in.
/// </returns>
public static DeclarationHeader CreateNewHeader(IDeclaration declaration, DocumentationRulesConfiguration docConfig)
{
IFile file = declaration.GetContainingFile();
using (WriteLockCookie.Create(file.IsPhysical()))
{
IDeclaration declarationTreeNode = declaration;
string middleText = StyleCopOptions.Instance.UseSingleLineDeclarationComments ? string.Empty : Environment.NewLine;
string emptyDocHeader = string.Format("<summary>{0}</summary>", middleText);
if (!(declarationTreeNode is IMultipleDeclarationMember))
{
emptyDocHeader = CreateDocumentationForElement((IDocCommentBlockOwnerNode)declaration, docConfig);
emptyDocHeader = emptyDocHeader.Substring(0, emptyDocHeader.Length - Environment.NewLine.Length);
}
string header = LayoutDocumentationHeader(emptyDocHeader);
IDocCommentBlockNode newDocCommentNode = Utils.CreateDocCommentBlockNode(file, header);
IDocCommentBlockOwnerNode docCommentBlockOwnerNode = Utils.GetDocCommentBlockOwnerNodeForDeclaration(declaration);
if (docCommentBlockOwnerNode != null)
{
docCommentBlockOwnerNode.SetDocCommentBlockNode(newDocCommentNode);
}
return(new DeclarationHeader(declaration));
}
}
/// <summary>
/// Returns an xml string of the documentation for an element.
/// </summary>
/// <param name="owner">
/// The owner of the doc comment block.
/// </param>
/// <param name="docConfig">
/// The config for the current ProjectFile.
/// </param>
/// <returns>
/// A string of the declarations summary text.
/// </returns>
private static string CreateDocumentationForElement(IDocCommentBlockOwnerNode owner, DocumentationRulesConfiguration docConfig)
{
ITreeNode element = owner;
IDeclaredElement declaredElement = (element is IDeclaration) ? ((IDeclaration)element).DeclaredElement : null;
StringBuilder text = new StringBuilder();
text.AppendLine("<summary>");
string summaryText = string.Empty;
if (element is IConstructorDeclaration)
{
summaryText = Utils.CreateSummaryForConstructorDeclaration((IConstructorDeclaration)element);
}
if (element is IDestructorDeclaration)
{
summaryText = Utils.CreateSummaryForDestructorDeclaration((IDestructorDeclaration)element);
}
if (element is IPropertyDeclaration)
{
summaryText = Utils.CreateSummaryDocumentationForProperty((IPropertyDeclaration)element);
}
text.AppendLine(summaryText);
text.AppendLine("</summary>");
ICSharpParametersOwnerDeclaration declarationWithParameters = element as ICSharpParametersOwnerDeclaration;
if (declarationWithParameters != null)
{
foreach (IRegularParameterDeclaration parameterDeclaration in declarationWithParameters.ParameterDeclarations)
{
text.AppendLine(Utils.CreateDocumentationForParameter(parameterDeclaration));
}
}
ICSharpTypeDeclaration typeDeclaration = element as ICSharpTypeDeclaration;
if (typeDeclaration != null && (typeDeclaration.TypeParameters.Count > 0))
{
foreach (ITypeParameterOfTypeDeclaration typeParameter in typeDeclaration.TypeParameters)
{
text.AppendLine(Utils.CreateDocumentationForParameter(typeParameter));
}
}
ITypeParametersOwner typeParametersOwner = element as ITypeParametersOwner;
if (typeParametersOwner != null && (typeParametersOwner.TypeParameters.Count > 0))
{
foreach (ITypeParameter typeParameter in typeParametersOwner.TypeParameters)
{
text.AppendLine(Utils.CreateDocumentationForTypeParameterDeclaration((ITypeParameterDeclaration)typeParameter));
}
}
IMethodDeclaration methodDeclaration = element as IMethodDeclaration;
if (methodDeclaration != null && (methodDeclaration.TypeParameterDeclarations.Count > 0))
{
foreach (ITypeParameterOfMethodDeclaration typeParameter in methodDeclaration.TypeParameterDeclarations)
{
text.AppendLine(Utils.CreateDocumentationForParameter(typeParameter));
}
}
IParametersOwner parametersOwner = declaredElement as IParametersOwner;
if ((parametersOwner != null && ((parametersOwner is IMethod) || (parametersOwner is IOperator))) &&
!parametersOwner.ReturnType.Equals(parametersOwner.Module.GetPredefinedType().Void))
{
text.AppendLine("<returns></returns>");
}
bool ruleIsEnabled = docConfig.GetStyleCopRuleEnabled("PropertyDocumentationMustHaveValue");
if (element is IPropertyDeclaration && ruleIsEnabled)
{
text.AppendLine(Utils.CreateValueDocumentationForProperty((IPropertyDeclaration)element));
}
List <IType> exceptions = new List <IType>();
ICSharpFunctionDeclaration functionDeclaration = element as ICSharpFunctionDeclaration;
if (functionDeclaration != null && functionDeclaration.Body != null)
{
CollectExceptions(functionDeclaration.Body, exceptions);
}
IPropertyDeclaration propertyDeclaration = element as IPropertyDeclaration;
if (propertyDeclaration != null)
{
CollectExceptions(propertyDeclaration.AccessorDeclarations, exceptions);
}
IIndexerDeclaration indexerDeclaration = element as IIndexerDeclaration;
if (indexerDeclaration != null)
{
CollectExceptions(indexerDeclaration.AccessorDeclarations, exceptions);
}
IEventDeclaration eventDeclaration = element as IEventDeclaration;
if (eventDeclaration != null)
{
CollectExceptions(eventDeclaration.AccessorDeclarations, exceptions);
}
foreach (IType exception in exceptions)
{
string presentableName = exception.GetPresentableName(CSharpLanguage.Instance);
string a = Utils.StripClassName(presentableName);
string b = exception.ToString();
text.AppendLine("<exception cref=\"" + Utils.SwapGenericTypeToDocumentation(a) + "\"></exception>");
}
return(text.ToString());
}
/// <summary>
/// Returns an xml string of the documentation for an element.
/// </summary>
/// <param name="owner">
/// The owner of the doc comment block.
/// </param>
/// <param name="docConfig">
/// The config for the current ProjectFile.
/// </param>
/// <returns>
/// A string of the declarations summary text.
/// </returns>
private static string CreateDocumentationForElement(IDocCommentBlockOwnerNode owner, DocumentationRulesConfiguration docConfig)
{
ITreeNode element = owner;
IDeclaredElement declaredElement = (element is IDeclaration) ? ((IDeclaration)element).DeclaredElement : null;
StringBuilder text = new StringBuilder();
text.AppendLine("<summary>");
string summaryText = string.Empty;
if (element is IConstructorDeclaration)
{
summaryText = Utils.CreateSummaryForConstructorDeclaration((IConstructorDeclaration)element);
}
if (element is IDestructorDeclaration)
{
summaryText = Utils.CreateSummaryForDestructorDeclaration((IDestructorDeclaration)element);
}
if (element is IPropertyDeclaration)
{
summaryText = Utils.CreateSummaryDocumentationForProperty((IPropertyDeclaration)element);
}
text.AppendLine(summaryText);
text.AppendLine("</summary>");
ICSharpParametersOwnerDeclaration declarationWithParameters = element as ICSharpParametersOwnerDeclaration;
if (declarationWithParameters != null)
{
foreach (ICSharpParameterDeclaration parameterDeclaration in declarationWithParameters.ParameterDeclarations)
{
text.AppendLine(Utils.CreateDocumentationForParameter(parameterDeclaration));
}
}
ICSharpTypeDeclaration typeDeclaration = element as ICSharpTypeDeclaration;
if (typeDeclaration != null && (typeDeclaration.TypeParameters.Count > 0))
{
foreach (ITypeParameterOfTypeDeclaration typeParameter in typeDeclaration.TypeParameters)
{
text.AppendLine(Utils.CreateDocumentationForParameter(typeParameter));
}
}
ITypeParametersOwner typeParametersOwner = element as ITypeParametersOwner;
if (typeParametersOwner != null && (typeParametersOwner.TypeParameters.Count > 0))
{
foreach (ITypeParameter typeParameter in typeParametersOwner.TypeParameters)
{
text.AppendLine(Utils.CreateDocumentationForTypeParameterDeclaration((ITypeParameterDeclaration)typeParameter));
}
}
IMethodDeclaration methodDeclaration = element as IMethodDeclaration;
if (methodDeclaration != null && (methodDeclaration.TypeParameterDeclarations.Count > 0))
{
foreach (ITypeParameterOfMethodDeclaration typeParameter in methodDeclaration.TypeParameterDeclarations)
{
text.AppendLine(Utils.CreateDocumentationForParameter(typeParameter));
}
}
IParametersOwner parametersOwner = declaredElement as IParametersOwner;
if ((parametersOwner != null && ((parametersOwner is IMethod) || (parametersOwner is IOperator)))
&& !parametersOwner.ReturnType.Equals(parametersOwner.Module.GetPredefinedType().Void))
{
text.AppendLine("<returns></returns>");
}
bool ruleIsEnabled = docConfig.GetStyleCopRuleEnabled("PropertyDocumentationMustHaveValue");
if (element is IPropertyDeclaration && ruleIsEnabled)
{
text.AppendLine(Utils.CreateValueDocumentationForProperty((IPropertyDeclaration)element));
}
List<IType> exceptions = new List<IType>();
ICSharpFunctionDeclaration functionDeclaration = element as ICSharpFunctionDeclaration;
if (functionDeclaration != null && functionDeclaration.Body != null)
{
CollectExceptions(functionDeclaration.Body, exceptions);
}
IPropertyDeclaration propertyDeclaration = element as IPropertyDeclaration;
if (propertyDeclaration != null)
{
CollectExceptions(propertyDeclaration.AccessorDeclarations, exceptions);
}
IIndexerDeclaration indexerDeclaration = element as IIndexerDeclaration;
if (indexerDeclaration != null)
{
CollectExceptions(indexerDeclaration.AccessorDeclarations, exceptions);
}
IEventDeclaration eventDeclaration = element as IEventDeclaration;
if (eventDeclaration != null)
{
CollectExceptions(eventDeclaration.AccessorDeclarations, exceptions);
}
foreach (IType exception in exceptions)
{
string presentableName = exception.GetPresentableName(CSharpLanguage.Instance);
string a = Utils.StripClassName(presentableName);
string b = exception.ToString();
text.AppendLine("<exception cref=\"" + Utils.SwapGenericTypeToDocumentation(a) + "\"></exception>");
}
return text.ToString();
}
/// <summary>
/// Creates a new DeclarationHeader for the declaration and assigns it to the declaration.
/// </summary>
/// <param name="declaration">
/// The declaration to create the header for.
/// </param>
/// <param name="docConfig">
/// Provides the configuration for the current ProjectFile.
/// </param>
/// <returns>
/// A DeclarationHeader for the declaration passed in.
/// </returns>
public static DeclarationHeader CreateNewHeader(IDeclaration declaration, DocumentationRulesConfiguration docConfig)
{
IFile file = declaration.GetContainingFile();
using (WriteLockCookie.Create(file.IsPhysical()))
{
IDeclaration declarationTreeNode = declaration;
IContextBoundSettingsStore settingsStore = PsiSourceFileExtensions.GetSettingsStore(null, declaration.GetSolution());
bool useSingleLineDeclarationComments = settingsStore.GetValue((StyleCopOptionsSettingsKey key) => key.UseSingleLineDeclarationComments);
string middleText = useSingleLineDeclarationComments ? string.Empty : Environment.NewLine;
string emptyDocHeader = string.Format("<summary>{0}</summary>", middleText);
if (!(declarationTreeNode is IMultipleDeclarationMember))
{
emptyDocHeader = CreateDocumentationForElement((IDocCommentBlockOwnerNode)declaration, docConfig);
emptyDocHeader = emptyDocHeader.Substring(0, emptyDocHeader.Length - Environment.NewLine.Length);
}
string header = LayoutDocumentationHeader(emptyDocHeader, declaration);
IDocCommentBlockNode newDocCommentNode = Utils.CreateDocCommentBlockNode(file, header);
IDocCommentBlockOwnerNode docCommentBlockOwnerNode = Utils.GetDocCommentBlockOwnerNodeForDeclaration(declaration);
if (docCommentBlockOwnerNode != null)
{
docCommentBlockOwnerNode.SetDocCommentBlockNode(newDocCommentNode);
}
return new DeclarationHeader(declaration);
}
}
/// <summary>
/// Returns a config object exposing the current config settings for this file.
/// </summary>
/// <param name="file">
/// The file to get the config for.
/// </param>
/// <returns>
/// The configuration for the given file.
/// </returns>
public DocumentationRulesConfiguration GetDocumentationRulesConfig(ICSharpFile file)
{
int hashCode = file.GetSourceFile().GetHashCode();
if (!this.docConfigFiles.ContainsKey(hashCode))
{
DocumentationRulesConfiguration a = new DocumentationRulesConfiguration(file.GetSourceFile());
this.docConfigFiles.Add(hashCode, a);
}
return (DocumentationRulesConfiguration)this.docConfigFiles[hashCode];
}
/// <summary>
/// Creates a new DeclarationHeader for the declaration and assigns it to the declaration.
/// </summary>
/// <param name="declaration">
/// The declaration to create the header for.
/// </param>
/// <param name="docConfig">
/// Provides the configuration for the current ProjectFile.
/// </param>
/// <returns>
/// A DeclarationHeader for the declaration passed in.
/// </returns>
public static DeclarationHeader CreateNewHeader(IDeclaration declaration, DocumentationRulesConfiguration docConfig)
{
IFile file = declaration.GetContainingFile();
using (WriteLockCookie.Create(file.IsPhysical()))
{
ITreeNode declarationTreeNode = declaration.ToTreeNode();
string middleText = StyleCopOptions.Instance.UseSingleLineDeclarationComments ? string.Empty : Environment.NewLine;
string emptyDocHeader = string.Format("<summary>{0}</summary>", middleText);
if (!(declarationTreeNode is IMultipleDeclarationMemberNode))
{
emptyDocHeader = CreateDocumentationForElement((IDocCommentBlockOwnerNode)declaration, docConfig);
emptyDocHeader = emptyDocHeader.Substring(0, emptyDocHeader.Length - Environment.NewLine.Length);
}
string header = LayoutDocumentationHeader(emptyDocHeader);
IDocCommentBlockNode newDocCommentNode = Utils.CreateDocCommentBlockNode(file, header);
IDocCommentBlockOwnerNode docCommentBlockOwnerNode = Utils.GetDocCommentBlockOwnerNodeForDeclaration(declaration);
if (docCommentBlockOwnerNode != null)
{
docCommentBlockOwnerNode.SetDocCommentBlockNode(newDocCommentNode);
}
return new DeclarationHeader(declaration);
}
}
