Specify XmlException LineNumber and LinePosition are zero-based

[carlossanlop]

Fixes: #851

Area owners: @buyaa-n and @krwq

[krwq]

@carlossanlop I believe we are starting to count with 1. The only thing to mention is that 0 can be encountered when user chooses to not use line info (which is the default). Specific line of code which is mentioned above ThrowWithoutLineInfo does not contain any line number information but since the values backed by int the 0 is probably arbitrary.

Easiest way to check:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Xml;
using System.Xml.Linq;
using System.IO;
using System.Text;

public class Program
{
  public static void Main()
  {
    using (MemoryStream ms = new MemoryStream(Encoding.UTF8.GetBytes("<foo>\r\n<ba</foo>")))
    {
      XDocument xdoc = XDocument.Load(ms, LoadOptions.SetLineInfo);
    }
  }
}

and observe exception:

System.Xml.XmlException: The '<' character, hexadecimal value 0x3C, cannot be included in a name. Line 2, position 4.

[carlossanlop]

@krwq thank you for the clarification. I'll adjust the descriptions.

[carlossanlop]

Here's an example that throws on line 1:

using System.IO;
using System.Text;
using System.Xml.Linq;

namespace ConsoleApp
{
    public class Program
    {
        public static void Main()
        {
            using (MemoryStream ms = new MemoryStream(Encoding.UTF8.GetBytes("<<foo>\r\nbar</foo>")))
            {
                XDocument xdoc = XDocument.Load(ms, LoadOptions.SetLineInfo);
            }
        }
    }
}

Exception message:
System.Xml.XmlException: 'Name cannot begin with the '<' character, hexadecimal value 0x3C. Line 1, position 2.'

[carlossanlop]

@mairaw I'm experimenting with adding an example in the Remarks section (without the Remarks title). I recall a few examples where we've done this, and Ron approved a couple of them. What do you think?

[mairaw]

It should be fine. I left a couple of comments for you to consider and apply to the other API as well.

[carlossanlop]

Here's the preview, @mairaw: https://review.docs.microsoft.com/en-us/dotnet/api/system.xml.xmlexception.linenumber?view=netcore-3.0&branch=pr-en-us-3636#System_Xml_XmlException_LineNumber

What do you think? Looks good to merge?

[mairaw]

I'll make some suggestions. Since what you're showing is anti-pattern, we probably should have this in the remarks instead and just show the little snippet that throws the exception. Makes sense?

[mairaw]

Left some suggestions for you to consider.

[mairaw]

I still don't think you need the remarks but I'll let you decide that. Left some comments in case you decide to keep them.