Specify XmlException LineNumber and LinePosition are zero-based (dotnet#3636)

carlossanlop · mairaw · web-flow · commit 11edd9b031b7 · 2019-12-10T16:39:22.000-08:00
* Specify XmlException LineNumber and LinePosition are zero-based

* suggestion by krwq

* suggestions by mairaw

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* suggestions by mairaw

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* remove example, mention exception message

* Space

* suggestions by mairaw

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;
diff --git a/xml/System.Xml/XmlException.xml b/xml/System.Xml/XmlException.xml
@@ -347,9 +347,22 @@ The `XmlException` is a generic XML-related error that is thrown if problems occ
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the line number indicating where the error occurred.</summary>
+        <summary>Gets the line number indicating where the error occurred. Line numbers start at 1.</summary>
         <value>The line number indicating where the error occurred.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Attempting to load the string `"<<foo>\r\nbar</foo>"` as XML throws an `XmlException` with the following message:
+
+`System.Xml.XmlException: 'Name cannot begin with the '<' character, hexadecimal value 0x3C. Line 1, position 2.'`
+
+Showing that line number is 1-based (the error is found in the first line).
+
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="LinePosition">
@@ -389,9 +402,21 @@ The `XmlException` is a generic XML-related error that is thrown if problems occ
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the line position indicating where the error occurred.</summary>
+        <summary>Gets the line position indicating where the error occurred. Line position starts at 1.</summary>
         <value>The line position indicating where the error occurred.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Attempting to load the string `"<<foo>\r\nbar</foo>"` as XML throws an `XmlException` with the following message:
+
+`System.Xml.XmlException: 'Name cannot begin with the '<' character, hexadecimal value 0x3C. Line 1, position 2.'`
+
+Showing that line position is 1-based (the error is found in the second character).
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Message">
