SubMain - CodeIt.Right The First Time!

/Community

Support Community for SubMain Products
 Home Products Services Download Purchase Support
in Search
 
Home Forums Blogs Tutorials/CIR Tutorials/GD Downloads
Welcome to SubMain Community Sign in | Join | Help

how to check whether a method has xml comments?

Last post 10-28-2014, 10:31 AM by Serge B. (SubMain). 11 replies.
Sort Posts: Previous Next
  •  10-27-2014, 12:59 AM 3984

    how to check whether a method has xml comments?

    I am trying to develop a custom rule "xml comments should be present in every function".  My target is "method". My check method is given below but it is also returning true for a method which has summary comments in it. HasXmlComments is not working properly

    public override bool Check(IElementInfo element)

            {

                ICodeElementInfo codeElementInfo = element as ICodeElementInfo;

                if (codeElementInfo == null)

                    return false;

                else 

                {

                    if(codeElementInfo.HasXmlComments)

                    {

                        return false;

                    }

                }

                return true;

            } 

  •  10-27-2014, 1:25 AM 3985 in reply to 3984

    Re: how to check whether a method has xml comments?

    Have you looked at the rule General -> Type, Member -> Should have XML comments? (Externally visible types and members should have XML comments)

    If that rule works for you, then there is no need to a custom rule?

    If you need to check XML Comment on every method (the rule does only check for externally visible ones), then you can just override the Check method behavior instead of writing a rule from scratch.

    Would this work for you?

     


    Thank you,
    Serge Baranovsky
    http://submain.com - .NET Developer Tools  |  Microsoft MVP  |  ASP Insider
    » » CodeIt.Right Will Fix Your Code!™ - http://submain.com/codeit.right
    » » C#/VB .NET Coding Guidelines - FREE 100+ page ebook (PDF) http://submain.com/guidelines
  •  10-27-2014, 2:14 AM 3986 in reply to 3985

    Re: how to check whether a method has xml comments?

    Serge B. (SubMain):

    Have you looked at the rule General -> Type, Member -> Should have XML comments? (Externally visible types and members should have XML comments)

    If that rule works for you, then there is no need to a custom rule?

    If you need to check XML Comment on every method (the rule does only check for externally visible ones), then you can just override the Check method behavior instead of writing a rule from scratch.

    Would this work for you?

     

     

     

    I have tried to use this rule but it is not raising a warning in the absence of xml comments inside my test code given below. 

     

    namespace ConsoleApplication1

    {

        class Test

        {

            public static int X; //For demonstration of static member rule

     

            public int Add(int a,int b) //For demonstration of try catch block rule

            {

     

                    //there are no xml comments here. why it is not giving any warning ?

                    return a + b;

       

            }

     

        }

     

     

        class Program

        {

            static void Main(string[] args)

            {

                Console.WriteLine("{0}", Test.X);

            }

        }

    }

     

    That is why I decided to reverse engineer this rule by decompiling its dll. In its dll, it is using HasXmlComments. I am unable to find any documentation of this function.  

  •  10-27-2014, 3:10 AM 3987 in reply to 3986

    Re: how to check whether a method has xml comments?

    Hello,

    There is no XML comments in your code. Please take a look at XML Documentation Comments (C# Programming Guide)

    Do you need to determine XML comments or simple comments (//)?

     


    Thank you,
    Misha Zhutov
    http://submain.com - .NET Developer Tools | Microsoft VB MVP
  •  10-27-2014, 3:33 AM 3989 in reply to 3987

    Re: how to check whether a method has xml comments?

    Misha Zhutov (SubMain):

    Hello,

    There is no XML comments in your code. Please take a look at XML Documentation Comments (C# Programming Guide)

    Do you need to determine XML comments or simple comments (//)?

     

     

    Yes I know that there is no xml comment in my code. "Should have xml comments" rule should raise a warning on my code. But no warning is generated. I need to just check xml comments, not simple comments 

  •  10-27-2014, 3:58 AM 3990 in reply to 3989

    Re: how to check whether a method has xml comments?

    Hi, 

    The TypesAndMembersShouldHaveXmlComments rule does not work for the following reason:

    1. class Test is not public. The rule (in built-in profile) works only for Public and Protected type/member. So, you need either create your own profile and edit rule in Profile Editor or add "public" modifier to class Test.

    2. Does your project have Xml documentation files flag set (Your Project->Properies->Build->Xml documentation file)? If no, you need either set it or edit the rule in Profile Editror and set Ignore 'Xml Documentation' flag.

     


    Thank you,
    Misha Zhutov
    http://submain.com - .NET Developer Tools | Microsoft VB MVP
  •  10-27-2014, 6:14 AM 3991 in reply to 3990

    Re: how to check whether a method has xml comments?

    Misha Zhutov (SubMain):

    Hi, 

    The TypesAndMembersShouldHaveXmlComments rule does not work for the following reason:

    1. class Test is not public. The rule (in built-in profile) works only for Public and Protected type/member. So, you need either create your own profile and edit rule in Profile Editor or add "public" modifier to class Test.

    2. Does your project have Xml documentation files flag set (Your Project->Properies->Build->Xml documentation file)? If no, you need either set it or edit the rule in Profile Editror and set Ignore 'Xml Documentation' flag.

     

     

    I have changes scope to any and target to method in the profile editor but this rule is still not working on my code. And no my code doesn't have  Xml documentation files flag set

  •  10-27-2014, 6:39 AM 3992 in reply to 3991

    Re: how to check whether a method has xml comments?

    Attachment: CIR_XmlComments.png

    I attached screenshot from Profile Editor. Please ensure that you have the same rule configuration.

     



    Thank you,
    Misha Zhutov
    http://submain.com - .NET Developer Tools | Microsoft VB MVP
  •  10-27-2014, 9:53 PM 3993 in reply to 3992

    Re: how to check whether a method has xml comments?

    Misha Zhutov (SubMain):

    I attached screenshot from Profile Editor. Please ensure that you have the same rule configuration.

     

     

    it worked after toggling xml documentation flag to true. Thanks. But I want to target just methods inside classes. But this rule is now detecting classes only. I have tried to change target to just method (by unchecking Type) but it is not detecting methods without xml comments 

  •  10-27-2014, 10:19 PM 3994 in reply to 3993

    Re: how to check whether a method has xml comments?

    abdulrauf:
    Misha Zhutov (SubMain):

    I attached screenshot from Profile Editor. Please ensure that you have the same rule configuration.

     

     

    it worked after toggling xml documentation flag to true. Thanks. But I want to target just methods inside classes. But this rule is now detecting classes only. I have tried to change target to just method (by unchecking Type) but it is not detecting methods without xml comments 

    I have found the problem. Problem is in check method of this rule (present in ).  Can I somehow override check method ? because decompiled dll by dotpeek isn't compiling

      public override bool Check(IElementInfo element)

        {

          ICodeElementInfo codeElementInfo = element as ICodeElementInfo;

          if (codeElementInfo == null)

            return false;

          IProjectInfo projectInfo = (IProjectInfo) null;

          IMemberInfo memberInfo = codeElementInfo as IMemberInfo;

          if (memberInfo != null)

          {

            ITypeInfo parent = memberInfo.Parent;

            if (parent != null)

            {

              if (!parent.IsPublic && !parent.IsProtected)  // This is the problem. This rule is detecting methods only in Public and Protected classes. I need to remove this if statement in the dll 

                return false;

              projectInfo = memberInfo.Parent.Project;

            }

          }

          ITypeInfo typeInfo = codeElementInfo as ITypeInfo;

          if (typeInfo != null)

          {

            if (this.IsContainXmlCommentInPartialClass(typeInfo))

              return false;

            projectInfo = typeInfo.Project;

          }

          return !this.IsLocatedInAspFile(codeElementInfo) && projectInfo != null && (this.CanProjectBeAnalyzed(projectInfo) && !RuleUtilities.IsMultipleFieldsDeclaration(codeElementInfo as IFieldInfo)) && !codeElementInfo.HasXmlComments;

        } 

     

  •  10-28-2014, 3:08 AM 3995 in reply to 3994

    Re: how to check whether a method has xml comments?

    Hi,

    The rule allows to check members only in public/protected type because xml documents make sense only for externally visible members.

    Anyway, if you would like to create custom rule please follow Tutorial: Creating Custom Rules. You can also reference SubMain.CodeItRight.Rules.General.dll (from Rules folder) and override TypesAndMembersShouldHaveXmlComments rule.

     


    Thank you,
    Misha Zhutov
    http://submain.com - .NET Developer Tools | Microsoft VB MVP
  •  10-28-2014, 10:31 AM 3996 in reply to 3995

    Re: how to check whether a method has xml comments?

    Here is example on how to change a rule's behavior without writing new custom rule from scratch - 

           Tutorial: Extending Existing Rules

    Thanks! 


    Thank you,
    Serge Baranovsky
    http://submain.com - .NET Developer Tools  |  Microsoft MVP  |  ASP Insider
    » » CodeIt.Right Will Fix Your Code!™ - http://submain.com/codeit.right
    » » C#/VB .NET Coding Guidelines - FREE 100+ page ebook (PDF) http://submain.com/guidelines
View as RSS news feed in XML
 
     
 
Home |  Products |  Services |  Download |  Purchase |  Support |  Community |  About Us |