0

I have this:

/// <summary>
/// Foo
/// </summary>
/// <seealso href="https://www.example.com/foo?q=bar&qux=2"/>

That gives:

XML comment has badly formed XML -- 'Reference to undefined entity 'qux'.' csharp(CS1570)

The problem is the & is invalid XML.

Workarounds:

  • convert & to &amp;
  • disable the warning with a #pragma warning disable CS1570
  • from comments below: <NoWarn>1570</NoWarn>
  • from comments below: find (using regex) and replace & with &amp;

These are non ideal and a waste of time - I just want to paste my URLs into the code and move on.

Is it possible to configure the analyzer to allow ampersands?

lonix
  • 14,255
  • 23
  • 85
  • 176
  • "Is it possible to configure the analyzer to allow ampersands?" - it wouldn't really be an XML format if it allowed invalid XML, would it? – Jon Skeet Jul 10 '21 at 06:06
  • @JonSkeet True! :-) But so what? Suppose one doesn't generate xml output with the compilation, and it's just for documentation for developers, those warnings get on one's nerves - it's like the argument about comments in JSON, devs are gonna do that regardless (hence jsonc). I concede your point though, thanks! – lonix Jul 10 '21 at 08:09
  • "But so what?" Um, so it's defined to be XML. If you don't want to use it as XML documentation, don't use `///` and just write in plain text. You can choose either "not XML" or "XML" but I don't think it's reasonable to say "Here's some XML, except it isn't really valid XML." Do you expect the compiler to also not mind if you don't write valid C# in a method, on the grounds that the method might not be called? – Jon Skeet Jul 10 '21 at 08:32
  • @JonSkeet Like I said I concede your point. However this is the same as the json/jsonc debate, which finally resulted in jsonc. I think a large number of devs use doccomments for internal use only, not for exporting to xml. So the compiler will not produce xml output for invalid nodes, but the analyzer should have a config option to allow it without warnings (for seealso nodes). – lonix Jul 10 '21 at 09:24
  • @JonSkeet "Do you expect the compiler to also not mind if you don't write valid C# in a method" That would be absolutely brilliant - I long for the day the compiler fixes my code for me. Then I can be lazy, and get paid too! You have some really good ideas Jon! :-) – lonix Jul 10 '21 at 09:26
  • If it's not XML, you shouldn't expect all the benefits of it being valid XML, e.g. references being clickable. In that case, why bother with an XML doc comment instead of a regular one? If you copied your URL into a *regular* comment, there'd be no problem. I don't see why there should be an option to not issue a warning when there's already an option to suppress warnings. That seems massively over-complicated to accommodate "I can't be bothered to follow the format that I've said I'm using". – Jon Skeet Jul 10 '21 at 09:51
  • 1
    The real fix is to have VS automatically fix your address as you paste it in a `seealso` `href` attribute value, like it already does when you paste in a json string -- it doubles `\\` characters automatically to keep paths valid. You should open a ticket on the Roslyn repository, with the understanding that it might get migrated to the VS repository instead, depending on where this is handled. – Blindy Jul 17 '21 at 20:48
  • @Blindy Thanks for the suggestion, [I did it](https://github.com/dotnet/roslyn/issues/54902). – lonix Jul 18 '21 at 03:06

1 Answers1

3

While you could disable this warning by adding <NoWarn>1570</NoWarn> to your .csproj file, this is also not an ideal solution, as the compiler will ignore documentation comments that have invalid XML - such comments will not be included in the compiler's XML output, and will not show up in tooltips in IDEs.

The best solution, if you are pasting a lot of URLs into your comments and don't want to fix them yourself, would be to do a find-and-replace on your source files to fix the invalid &s to &amp;. This could be done as a pre-build event so that it runs before every build.

JosephDaSilva
  • 1,107
  • 4
  • 5
  • So there's no way to configure the analyzer to allow ampersands? Nice idea BTW, I'm gonna do that - thanks! – lonix Jul 10 '21 at 08:06