SA1645: How does StyleCop resolve include paths?

Apr 23, 2011 at 12:40 AM
Edited Apr 23, 2011 at 12:42 AM

Hi,

I'm using the XML documentation comments <include file='Foo.xml' path='...' /> element.  The C# compiler has no problem resolving my external XML file and including its contents in the XML doc file; however, StyleCop generates the following warning:

Warning 1 SA1645: The included documentation header file does not exist or cannot be loaded: Foo.xml C:\...excluded_path...\Foo - Test - 1.cs

First of all, I just want to be sure that "documentation header file" actually means "external XML documentation comments file".  (I'm not sure about the term "header" in this context.)

The folder structure relative to the project root is as follows:

{Project Root}\System\Linq\Foo - Test - 1.cs

The XML doc comments file is in the same folder:

{Project Root}\System\Linq\Foo.xml

Edit: Just to be clear, the include is as follows; i.e., only a name in the file attribute, no path:

<include file='Foo.xml' path='//doc/excluded_blah_blah/*' />

Furthermore, the namespace in the .cs file is different than the default namespace of the project because it contains LINQ extensions that I want included by specifying using System.Linq.  I hope that StyleCop doesn't take this into account when attempting to resolve the path to Foo.xml.

On a related note, I cannot find SA1645 in the settings UI to disable it.  Was this an oversight or was it purposefully excluded?

Thanks,
Dave

Apr 23, 2011 at 4:07 AM
Edited Apr 23, 2011 at 4:10 AM

Hi,

Specifying the path relative to the project folder removes the StyleCop warning:

<include file='System\Linq\Foo.xml' path='//doc/excluded_blah_blah/*' />

However, a project-relative path isn't necessary for the C# compiler to resolve a doc file that is in the same directory as the source code file.  StyleCop shouldn't warn about the following usage:

<include file='Foo.xml' path='//doc/excluded_blah_blah/*' />

Thanks,
Dave

May 4, 2011 at 2:13 AM

I can confirm the same issue in 4.5.0.6.  In my case, the *.xml file is at the project level, but is referenced/included in a subfolder/namespace.

{project}\comments.xml

{projects\data\foo.cs

The compiler has no problem resolving <include file="comments.xml" path="..." /> from Data\Foo.cs

Aug 17, 2011 at 8:16 PM
Edited Aug 17, 2011 at 8:17 PM

Hi,

This is still broken for me in StyleCop 4.5.25.0.

I tried including a new XML file and I'm still getting SA1645 even though the C# compiler doesn't generate any warnings - I've also confirmed that the XML doc file that the compiler creates contains the comments from the included file.

Source code file:

{Project Root}\System\Reactive\Linq\Observable2 - Dictionary.cs

XML include file:

{Project Root}\System\Reactive\Linq\Observable2 - Collection and Dictionary.xml

The include element that I'm using in the source code comments:

/// <include file='Observable2 - Collection and Dictionary.xml' path='//extension[@name="Collect"]/remarks'/>

Unfortunately, since I apparently can't disable this rule I'm stuck with either a whole bunch of warnings after each build or I must go against DRY and copy the same large comment blocks into every method of every source code file that needs it.  So even if this issue can't (or won't) be fixed, I'd really appreciate it if I could at least disable the warning; especially since the C# compiler provides a similar warning already.

Thanks,
Dave

Aug 17, 2011 at 8:24 PM

Hi,

In case you need to repro, I've checked in the source code that produces the StyleCop warnings:

http://rxx.codeplex.com/SourceControl/changeset/changes/62634 

- Dave

Coordinator
Aug 18, 2011 at 2:54 PM
Edited Aug 18, 2011 at 2:55 PM

Right. I've investigated and it is indeed broken - sorry. The fix will be in 4.5 SP1 and 4.6.next.build in the next few weeks.

Aug 18, 2011 at 9:09 PM
Edited Aug 18, 2011 at 9:09 PM

No problem, thanks!

- Dave