Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

VS2010: Autogenerated files and XML documentation

This is really just re-asking this question asked about Visual Studio 2008. Does VS2010 offer any feature to get rid of the CS1591 compiler warning for auto-generated code?

CS1591: Missing XML comment for publicly visible type or member

To quote the question for VS2008:

This is an annoyance more than a problem. My project contains a number of autogenerated files (using mgmtclassgen.exe). When I generate the XML documentation, my beautifully commented library is plagued by xml documentation warnings from these autogen files.

Is there a way to either a) suppress generating documentation for these files or b) suppress warning CS1591 just for a set of files? I obviously do not want to modify files that are autogenerated, even if to just add suppression pragmas.

EDIT: In my case, the offending files are generated by WCF RIA Services, so the file that is generating the errors is the auto-generated WebContext class (MyProject.BusinessApplication.Web.g.cs).

I cannot hand modify this file because it is generated on the fly, all changes will be wiped out. I also don't want to globally disable the warning, as it is helpful in my non-autogenerated code.

like image 619
Andrew Garrison Avatar asked Sep 02 '10 18:09

Andrew Garrison


People also ask

What is XML documentation in C#?

The C# compiler combines the structure of the C# code with the text of the comments into a single XML document. The C# compiler verifies that the comments match the API signatures for relevant tags. Tools that process the XML documentation files can define XML elements and attributes specific to those tools.

How do I create an XML document in Visual Studio?

From the menu bar, choose Tools > Options to open the Options dialog box. Then, navigate to Text Editor > C# (or Visual Basic) > Advanced. In the Editor Help section, look for the Generate XML documentation comments option.

What is param tag in C#?

<param> Tag The <param> tag is used to describe parameters for a method or constructor. Let's say we have a method that adds two numbers together and returns the result as follows. 1 /// <param name="operand1">the left side operand.</

How do I auto generate comments in Visual Studio?

The only way I know to do this is on the line right above your method just type "///" and it will generate a comment template based on the method.


1 Answers

I was having a similar issue with auto-generated entity framework classes. I managed to solve it by modifying the template file. This obviously won't work for all auto-generated scenarios and it may not apply to your particular RIA scenario, but I'll post here for anybody else that may be having the same issue.

Open the template file (something.tt) and find the auto-generated xml comment section

//------------------------------------------------------------------------------
// <auto-generated>
//    This code was generated from a template.
//
//    Manual changes to this file may cause unexpected behavior in your application.
//    Manual changes to this file will be overwritten if the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

Add the following line right after the comment block

#pragma warning disable 1591 

A little below that, you should find where the namespace block ends. It will probably look something like this

if (!String.IsNullOrEmpty(ObjectNamespace))
{
    PopIndent();
#>
}

Place the following line after that closing brace

#pragma warning restore 1591

If everything worked correctly, whenever your classes are auto-generated by Entity Framework, they should be wrapped by the disable/restore pragma statements. This should suppress the warnings about no XML comments in your EF classes without suppressing the warnings at the project level.

like image 155
Tallek Avatar answered Sep 19 '22 05:09

Tallek