How to disable warnings related to XML comments in Visual Studio?

Sometimes there are cases when XML comments generated by VSdocman can cause VS warnings. It's because VSdocman uses extended syntax. Here we explain how to disable such warnings.

VSdocman supports XML comments for all types of elements, including namespaces. Visual Studio, however, doesn't support XML comments for a namespace.

In C#

You'll get the following warning:

XML comment is not placed on a valid language element
It's numeric code is 1587.

Suppressing is quite easy. In C#, you have two options - you can suppress the warning whether globally for entire project or locally for just a part of your code.

1. Globally

You can enter a comma delimited list of warning IDs in project's Properties - Build tab, Errors and warnings section. So add 1587 there.

2. Locally

Use #pragma warning disable in your code. For example:

#pragma warning disable 1587
/// <summary>
/// This is main namespace.
/// </summary>
/// <remarks>
/// <para>You can navigate to code elements using clickable class diagram below. The
/// diagram can be placed anywhere, e.g. in summary or Remarks section or in its own
/// section as shown here.</para>
/// <para> <img src="ClassDiagram1.cd"/></para>
/// </remarks>
namespace SampleClassLibrary
#pragma warning restore 1587
{
...

 

In VB .NET

You'll get the following warning:

XML documentation comments must precede member or type declarations.

or in older VS versions:

XML comment block cannot be associated with any language element that supports the application of XML documentation comments. XML comment will be ignored.

It's numeric code is 42312.

You can suppress this warning only globally in VB .NET. You need to manually edit project .vbproj file.

  1. Close VS.
  2. Open .vbproj file. Find <NoWarn> tag and add the warning ID there. In our case the ID is 42312: <NoWarn>42312</NoWarn>. Don’t place any whitespaces and newlines in this tag! There is one <NoWarn> section for each configuration (Release/Debug) so you need to edit all of them.
  3. Save the .vbproj file and open VS.

 

After this, you shouldn’t get specified warnings during the build, nor should you see warning underline during editing.

 

Start generating your .NET documentation now!
DOWNLOAD
Free, fully functional trial
VSdocman Tip
You can define your own documentation output format by creating or modifying an output template.
Customers

Universities
Medical institutions
Government institutions
Large financial institutions
Thousands of SW companies

Deloitte & Touche
PricewaterhouseCoopers
Bloomberg
Wells Fargo
QBE

Caterpillar
Lear
DuPont
Pfizer

Boeing
Airbus
Rolls-Royce Naval Marine
Toyota Motorsport

Bose
Mitsubishi Electric
Johnson Controls
Bentley Systems

Intel
Hewlett Packard
Bosch (Australia)
Schneider Electric

Intergraph
Volvo Information Technology
SOPRA GROUP
Agilent Technologies
Tesco SW

Syncfusion
T-Systems
Verizon
Fraunhofer Heinrich-Hertz-Institut

vs launch partner logo

VS Mag award VS Mag award

A few years ago, we gave a test to several products to document our source code. We finally chose VSdocman mostly because it was easy to use, from within the development environment, making training of programmers useless. It provides flexible features which enables producing complete documentation for people using our products and also for internal use. When technical support is required (we needed this when switching to VS 2015), Peter answered our emails very quickly. After more than 3 years with VSdocman, we strongly recommend the product which is amazingly easier to use than SandCastle.

Pierrick Combreau, Product Manager, Quotalys Ltd