/// <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); } }