locked
Compiler warning for missing xml comment when i have generated code RRS feed

  • Question

  •  

    Hi,

     

    I have a C# / .Net 3.5 project where i have a reference to a WCF service. When i create the reference, VS 2008 generates a bunch of code files. The problem is, that theses files doesn't have xml comments. When im compiling my project, I get a lot of "Missing XML comment for publicly visible type or member....."....

     

    Is there a way to hide these messages for generated code? I am very happy to get the warnings if i have forgotten to make an XML comment in my custom code. But its hard to find my own few mistakes when the compiler shows 200 warnings...

     

    -Thanks,

     

    Kaj

    Wednesday, March 26, 2008 10:05 AM

All replies

  • Hi!

    I'm facing the same problem now, did you find any solution for this issue?

    Thursday, March 19, 2009 10:30 AM
  • This solution works for Visual Studio 2005. VS2008 and VS2010 may differ.

    From the VS2005 menu, select &Project | %PROJECTNAME% &Properties...

    Select the "Build" tab.

    In the Form, look down in the Output section and UNCHECK "&XML documentation file:"

    Your code must be well documented in order to generate the XML documentation file.
    Thursday, July 9, 2009 4:36 PM
  • Anyone who found a REAL solution to this?

    jp2msft: The problem is not whether our code is well documented. The problem is that the WSDL autogenerated code is NOT.
    In my case I have an assembly that includes a webreference. The assembly is well-documented, and I of course have XML Doc enabled, so I get intellisense in other projects that reference this assembly. However I get 724(!) warnings all because of warnings in the reference.cs files generated by the service references. Now if I forget to document one of my methods (because I want to keep my project well documented) or create some other kind of warning, I won't notice, because they are all disquised by the sheer number of warnings that I get from the autogenerated code.

    Basically the problems is really in the wsdl compiler. It should add empty <summary/> tags to all classes, properties and methods. However it does not, and we NEED a solution to this. Yes I could go and do this manually or add "#pragma warning disable 1591" to each class (tedious), but they are lost the moment the reference is updated and the code regenerated.
    Friday, September 11, 2009 9:53 PM
  • Hi Morten,

    I hope I didn't offend you with my suggestions. I'm not suggesting your code isn't well documented; only that it may not be documented the way the compiler recommends.

    Are you using these XML style comments?
    /// <summary>
    /// Get and Set Property for Local Directory Path (My Docs?) is Public so Eric can set this from his app
    /// </summary>
    public string LocalDirectory { get; set; }
    If you are doing this already, I apologize. Adding these XML style comments to all of my public properties and methods eliminated the problem you described.

    Regards,
    Joe

    Avoid Sears Home Improvement
    • Edited by jp2code Monday, November 30, 2009 4:59 PM poor formatting in editor
    Sunday, September 13, 2009 1:28 AM
  • jp2msft: Are you really suggesting we should XML document every public entry in a machine generated code file (reference.cs) every time we update the service reference?
    Monday, November 30, 2009 4:23 PM
  • I am just saying I looked into this before, and that was the solution I saw.

    If you have the settings for your project set to generate the XML documentation file, you will need to write something for the public entries in your project so the XML Documentation Generator can do what you are telling it to do.

    I'm not saying anyone's method of documenting is bad, only to uncheck this option if you are getting these warning messages and you don't want to see them.

    I'm really wishing I hadn't said anything here. My explanation is obviously unclear.

    ~Joe

    Avoid Sears Home Improvement
    Monday, November 30, 2009 4:45 PM
  • The simplest solution is to just suppress the warning by entering it's number (1591 for C#) in the Suppress Warnings field on the Build tab of the project properties.  You can always remove it if you need to find missing comments in your actual code at a later date when you feel like wading through all the extra irrelevant messages produced by the tool-generated code.

    If you're using Sandcastle to produce a help file and/or Intellisense file for your assembly, you can use the ShowMissingComponent available at the Sandcastle Help File Builder project (standalone or built into SHFB) to find missing comments in the documented API.  That would give you less to look at since you can filter out elements that you don't want documented and the warnings can be found in the build log file or just by searching the resulting help file for the keyword "missing" since it adds notes to the members to note the missing comments.

    Eric
    • Proposed as answer by EWoodruff Monday, November 30, 2009 8:30 PM
    Monday, November 30, 2009 8:30 PM
  • There does not seem to be an easy way. The best way I have found is to edit the Reference.cs file itself and add "#pragma warning disable 1591" at the top and "#pragma warning restore 1591" at the bottom.

    It has to be done each time the Web Reference is updated, which is a pain, but it does allow me to see where there are documentation issues in my own code that need fixing.
    • Proposed as answer by TTowers Friday, December 4, 2009 2:04 PM
    Friday, December 4, 2009 2:04 PM
  • JP2MSFT,

         You either don't understand the problem being discussed here or don't understand basic software engineering.  Please refrain from commenting, they are not helpful.

    Original Poster,
         I've got the exact same problem with the Settings.  Any project that attempts to use Settings and the automatically generated XML documentation will run into this issue.  If you've got a large library and want to make sure your junior engineers are contributing solid code, this becomes a real issue.  I let it get away from me at the start of a large project and now I've got hundreds of undocumented classes, properties and methods.

    TTTowers,
         I ran across the #pragma solution also.  Thanks for posting.  It's ugly.  Please let me know if you find anything better.  I'll do the same.  Thanks.

    Don Airey
    Monday, December 7, 2009 2:37 PM
  • Don (and all) --

    Did you find a better solution to this?

    I suppose I will write a macro that will put the pragma in all "*.designer.cs" files; but, even that is ugly.

    What do you think?

    Please advise.

    Thank you.

    -- Mark Kamoski


    mkamoski
    Friday, April 23, 2010 3:05 PM
  • Mark,

         No.  But I can tell you the feature did not make it into VS2010.  I'm having a tough time understanding what the VS engineers have been doing for the last 2 years, but they've not been focused on the nuts-and-bolts issues for creating LOB applications.  This upgrade (and the wait) have NOT been worth the effort.

         One of these days I'm going to get tired of hacking the resource file and just write my own CodeDOM generator.  It shouldn't be that hard.

    FWIW,

    Don

    Friday, April 23, 2010 7:47 PM
  • Hi all,

    i ran into this problem too, caused by a service reference with missing xml documentation but i also wanted to keep a chance to get informed about documentation errors in the rest of the project. My solution was (i know its surely not the best way, but it works well for me) i just installed the free AddIn "StyleCop" and suppressed all warnings with code 1591 via project properties. With StyleCop u can set what should be checked, so your project can still be tested for documentation errors with few clicks.

    Hope this helped some ppl out ;)

     

    Felix

    Friday, May 7, 2010 1:30 PM
  • All --

    BTW, I have found that if I integrate StyleCop, as show at the following link...

    http://blogs.msdn.com/sourceanalysis/pages/source-analysis-msbuild-integration.aspx

    ...then that gives one the option of turning off such warnings in generated code, etc.

    As such, I once had the same issue in my code but now it is gone.

    HTH.

    Thank you.

    -- Mark Kamoski

    • Edited by mkamoski3 Friday, May 14, 2010 1:06 PM added link
    Friday, May 7, 2010 6:35 PM
  • I definitely agree that MS should be putting "#pragma warning disable 1591" in all their designer files. 
    Thursday, May 13, 2010 5:55 PM
  • I definitely agree that MS should be putting "#pragma warning disable 1591" in all their designer files. 

    Paul --

    Regarding updating designer files, this may be of interest or help to you...

    "

    MSDN

    Visual Studio 2008 

    Visual Studio Templates

    Customizing Project and Item Templates

    How to: Update Existing Templates

    http://msdn.microsoft.com/en-us/library/ms185319(VS.90).aspx

    "

    I have not tried editing the templates used for designer files; but, I suspect that it would work.

    I have not tried it because I am using StyleCop integration, as I mention above, and that handles the pragma issue so you might want to look at this link...

    http://blogs.msdn.com/sourceanalysis/pages/source-analysis-msbuild-integration.aspx 

    ...which shows how easy it is to integrate StyleCop, which then gets rid of this pesky pragma warning for designer and other generated files.)

    HTH.

    Thank you.

    -- Mark Kamoski

    • Edited by mkamoski3 Friday, May 14, 2010 1:05 PM improved clarity
    Friday, May 14, 2010 12:59 PM
  • One way I have been approaching this issue is by issolating the service references in its own project and suppressing the warning 1591 with in the build properties of that project

     


    Mike K.
    Tuesday, November 2, 2010 10:51 PM
  • The approach described here http://lvquoc.blogspot.com/2010/11/disable-xml-comment-warning-in-workflow.html may be applied to solve this problem.
    Thursday, December 16, 2010 3:55 PM
  • TTTowers,
         I ran across the #pragma solution also.  Thanks for posting.  It's ugly.  Please let me know if you find anything better.  I'll do the same.  Thanks

    Found a solution in VS2008, provided you're happy with the reference not being publically available.

    Right click on the service reference and choose configure

    Change "Access level for generated classes" to Internal.

    Click OK.

    I have a feeling this won't help everyone, but hopefully some.

     

    Tony Towers.

    • Proposed as answer by buzzdug Thursday, April 14, 2011 2:57 PM
    Friday, February 4, 2011 12:09 PM
  • @TTowers: Your solution is the one I was looking for. Thanks!

    Thursday, April 14, 2011 2:57 PM
  • Eric's reply works. However besides his suggestion of getting the missing documentation from the Sandcastle build process, Stylecop will also show the missing documentation and it does not report on missing documentation on auto-generated code.
    Friday, June 8, 2012 6:07 PM
  • I think you fail to understand how many people build software.

    Daily the software is being built and verified. When the build completes, any warnings and errors are reported to the developer team, and anyone who introduced an error or warning is responsible for fixing it (nevermind the fact that these days we now have gated check ins to prevent this, but that only makes it worse since the checkin would get rejected).
    We ensure we don't have any warnings in our code, because these could be potential issues, or code that we simply forgot to document. The xml doc is very important to us.

    So if we disable warnings about missing documentation, we will never catch this problem in our code files, If we enable it, we will have 100s of warnings that will mask the "important" ones, and people will get used to ignoring warnings.

    I have added the pragma warnings to the top of each reference.cs file, and that disables it just for that class, so we can move on. However, every time you regenerate the proxy, you will have to re-insert this. It would be nice if the wsdl generator would generate code properly in the first place.

    Friday, June 8, 2012 10:46 PM
  • >So if we disable warnings about missing documentation, we will never catch this problem in our code files, If we enable it, we will have 100s of warnings that will mask the "important" ones, and people will get used to ignoring warnings.

    I agree with you that warnings should not be ignored, however until Microsoft, Crystal Reports ect get their auto-generated code in order, we must look for work-arounds.

    I suggest that you look at running stylecop as part of your build process. This avoids adding pragma warnings to files that will be automatically re-generated. See the discussion at http://stylecop.codeplex.com/discussions/223085

    Friday, June 8, 2012 11:47 PM
  • Morten:

    If you use generated code provided by Visual Studio who is at fault?   I would love for the documentation to carry across the web service interface however it does not and we get warnings.

    In order to work around this limitation of visual studio (not the coder), as per the discussion,  set the web service to internal and the documentation is not generated and we do not get 1591 warnings.

    I repeat this is a work around for a fault in the Visual studio template code, not the coder.


    Ta Ken

    Wednesday, July 18, 2012 12:34 AM
  • Have a look at the workaround below, it is another way to overcome the issue

    • http://lvquoc.blogspot.com/2010/11/disable-xml-comment-warning-in-workflow.html

    Quoc

    Wednesday, July 18, 2012 2:54 AM
  • The most reliable way I have found to do this is to move the generated code into a separate project, and disable XML documentation on that project.  This keeps all of the generated proxy code separate from the code that I actually care to document.

    Thursday, August 2, 2012 7:20 PM