docs: convert javadoc to xml (#318)

* docs: convert javadoc to xml

* docs: address copilot comments

Author: wmundev

csharp/PhoneNumbers.Test/TestAreaCodeMap.cs

@@ -19,11 +19,10 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-    * Unittests for AreaCodeMap.java
-    *
-    * @author Shaopeng Jia
-    */
+    /// <summary>
+    /// Unittests for AreaCodeMap.java
+    /// </summary>
+    /// <remarks>Author: Shaopeng Jia</remarks>
     [Collection("TestMetadataTestCase")]
     public class TestAreaCodeMap
     {

csharp/PhoneNumbers.Test/TestAsYouTypeFormatter.cs

@@ -18,14 +18,13 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-    * Unit tests for AsYouTypeFormatter.java
-    *
-    * Note that these tests use the test metadata, not the normal metadata file, so should not be used
-    * for regression test purposes - these tests are illustrative only and test functionality.
-    *
-    * @author Shaopeng Jia
-    */
+    /// <summary>
+    /// Unit tests for AsYouTypeFormatter.java
+    /// 
+    /// Note that these tests use the test metadata, not the normal metadata file, so should not be used
+    /// for regression test purposes - these tests are illustrative only and test functionality.
+    /// </summary>
+    /// <remarks>Author: Shaopeng Jia</remarks>
     [Collection("TestMetadataTestCase")]
     public class TestAsYouTypeFormatter
     {

csharp/PhoneNumbers.Test/TestExampleNumbers.cs

@@ -26,11 +26,10 @@ public class TestExampleNumbers
         private readonly List<PhoneNumber> invalidCases = new List<PhoneNumber>();
         private readonly List<PhoneNumber> wrongTypeCases = new List<PhoneNumber>();
 
-        /**
-        * @param exampleNumberRequestedType  type we are requesting an example number for
-        * @param possibleExpectedTypes       acceptable types that this number should match, such as
-        *     FIXED_LINE and FIXED_LINE_OR_MOBILE for a fixed line example number.
-        */
+        /// <summary>
+        /// </summary>
+        /// <param name="exampleNumberRequestedType">type we are requesting an example number for</param>
+        /// <param name="possibleExpectedTypes">acceptable types that this number should match, such as FIXED_LINE and FIXED_LINE_OR_MOBILE for a fixed line example number.</param>
         private void CheckNumbersValidAndCorrectType(PhoneNumberType exampleNumberRequestedType,
             HashSet<PhoneNumberType> possibleExpectedTypes)
         {

csharp/PhoneNumbers.Test/TestMappingFileProvider.cs

@@ -19,11 +19,10 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-    * Unittests for MappingFileProvider.java
-    *
-    * @author Shaopeng Jia
-    */
+    /// <summary>
+    /// Unittests for MappingFileProvider.java
+    /// </summary>
+    /// <remarks>Author: Shaopeng Jia</remarks>
     [Collection("TestMetadataTestCase")]
     public class TestMappingFileProvider
     {

csharp/PhoneNumbers.Test/TestMedataManager.cs

@@ -18,11 +18,10 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-    * Some basic tests to check that the phone number metadata can be correctly loaded.
-    *
-    * @author Lara Rennie
-    */
+    /// <summary>
+    /// Some basic tests to check that the phone number metadata can be correctly loaded.
+    /// </summary>
+    /// <remarks>Author: Lara Rennie</remarks>
     public class TestMedataManager
     {
         [Fact]

csharp/PhoneNumbers.Test/TestMetadataFilter.cs

@@ -23,9 +23,9 @@ namespace PhoneNumbers.Test
 {
 
 
-/**
- * Unit tests for {@link MetadataFilter}.
- */
+/// <summary>
+/// Unit tests for <see cref="MetadataFilter"/>.
+/// </summary>
     public class MetadataFilterTest
     {
         private const string ID = "AM";

csharp/PhoneNumbers.Test/TestMetadataTestCase.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright (C) 2012 The Libphonenumber Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,15 +16,15 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-    * Root class for PhoneNumberUtil tests that depend on the test metadata file.
-    * <p>
-    * Note since tests that extend this class do not use the normal metadata file, they should not be
-    * used for regression test purposes.
-    *
-    * @author Shaopeng Jia
-    * @author Lara Rennie
-    */
+    /// <summary>
+    /// Root class for PhoneNumberUtil tests that depend on the test metadata file.
+    /// <para>
+    /// Note since tests that extend this class do not use the normal metadata file, they should not be
+    /// used for regression test purposes.
+    /// </para>
+    /// </summary>
+    /// <remarks>Author: Shaopeng Jia</remarks>
+    /// <remarks>Author: Lara Rennie</remarks>
     public class TestMetadataTestCase
     {
         public static readonly PhoneNumberUtil PhoneUtil = new PhoneNumberUtil("PhoneNumberMetadataForTesting.xml", typeof(TestMetadataTestCase).Assembly);

csharp/PhoneNumbers.Test/TestNumberFormat.cs

@@ -2,9 +2,9 @@
 
 namespace PhoneNumbers.Test
 {
-    /**
-     * Tests derived from https://github.com/google/libphonenumber/blob/master/java/libphonenumber/test/com/google/i18n/phonenumbers/PhonenumberTest.java
-     */
+    /// <summary>
+    /// Tests derived from https://github.com/google/libphonenumber/blob/master/java/libphonenumber/test/com/google/i18n/phonenumbers/PhonenumberTest.java
+    /// </summary>
     public class TestNumberFormat
     {
         [Fact]

csharp/PhoneNumbers.Test/TestPhoneNumberMatch.cs

@@ -37,9 +37,9 @@ public void TestValueTypeSemantics()
             Assert.Equal("1 800 234 45 67", match1.RawString);
         }
 
-        /**
-        * Tests the value type semantics for matches with a null number.
-        */
+        /// <summary>
+        /// Tests the value type semantics for matches with a null number.
+        /// </summary>
         [Fact]
         public void TestIllegalArguments()
         {

csharp/PhoneNumbers.Test/TestPhoneNumberMatcher.cs

@@ -192,9 +192,9 @@ public void TestFindInterspersedWithSpace()
             DoTestFindInContext("0 3   3 3 1   6 0 0 5", "NZ");
         }
 
-        /**
-        * Test matching behavior when starting in the middle of a phone number.
-        */
+        /// <summary>
+        /// Test matching behavior when starting in the middle of a phone number.
+        /// </summary>
         [Fact]
         public void TestIntermediateParsePositions()
         {
@@ -403,9 +403,9 @@ public void TestDoesNotMatchMultiplePhoneNumbersSeparatedWithNoWhiteSpace()
             Assert.True(HasNoMatches(phoneUtil.FindNumbers(text, region)));
         }
 
-        /**
-         * Strings with number-like things that shouldn't be found under any level.
-         */
+        /// <summary>
+        /// Strings with number-like things that shouldn't be found under any level.
+        /// </summary>
         private static readonly NumberTest[] ImpossibleCases =
         {
             new NumberTest("12345", "US"),
@@ -423,9 +423,9 @@ public void TestDoesNotMatchMultiplePhoneNumbersSeparatedWithNoWhiteSpace()
             new NumberTest("20120102 08:00", RegionCode.US)
         };
 
-        /**
-         * Strings with number-like things that should only be found under "possible".
-         */
+        /// <summary>
+        /// Strings with number-like things that should only be found under "possible".
+        /// </summary>
         private static readonly NumberTest[] PossibleOnlyCases =
         {
             // US numbers cannot start with 7 in the test metadata to be valid.
@@ -437,10 +437,10 @@ public void TestDoesNotMatchMultiplePhoneNumbersSeparatedWithNoWhiteSpace()
             new NumberTest("(20) 3346 1234", RegionCode.GB) // Non-optional NP omitted
         };
 
-        /**
-         * Strings with number-like things that should only be found up to and including the "valid"
-         * leniency level.
-         */
+        /// <summary>
+        /// Strings with number-like things that should only be found up to and including the "valid"
+        /// leniency level.
+        /// </summary>
         private static readonly NumberTest[] ValidCases =
         {
             new NumberTest("65 02 53 00 00", "US"),
@@ -464,10 +464,10 @@ public void TestDoesNotMatchMultiplePhoneNumbersSeparatedWithNoWhiteSpace()
             new NumberTest("0 3 0 -3 2 23 12 34", RegionCode.DE)
         };
 
-        /**
-         * Strings with number-like things that should only be found up to and including the
-         * "strict_grouping" leniency level.
-         */
+        /// <summary>
+        /// Strings with number-like things that should only be found up to and including the
+        /// "strict_grouping" leniency level.
+        /// </summary>
         private static readonly NumberTest[] StrictGroupingCases =
         {
             new NumberTest("(415) 6667777", "US"),
@@ -482,9 +482,9 @@ public void TestDoesNotMatchMultiplePhoneNumbersSeparatedWithNoWhiteSpace()
             new NumberTest("0 900-1 123123", RegionCode.DE)
         };
 
-        /**
-         * Strings with number-like things that should be found at all levels.
-         */
+        /// <summary>
+        /// Strings with number-like things that should be found at all levels.
+        /// </summary>
         private static readonly NumberTest[] ExactGroupingCases = {
             new NumberTest("\uFF14\uFF11\uFF15\uFF16\uFF16\uFF16\uFF17\uFF17\uFF17\uFF17", "US"),
             new NumberTest("\uFF14\uFF11\uFF15-\uFF16\uFF16\uFF16-\uFF17\uFF17\uFF17\uFF17", "US"),
@@ -634,13 +634,13 @@ private void DoTestNumberNonMatchesForLeniency(List<NumberTest> testCases,
             Assert.Equal(0, matchFoundCount);
         }
 
-        /**
-         * Helper method which tests the contexts provided and ensures that:
-         * -- if isValid is true, they all find a test number inserted in the middle when leniency of
-         *  matching is set to VALID; else no test number should be extracted at that leniency level
-         * -- if isPossible is true, they all find a test number inserted in the middle when leniency of
-         *  matching is set to POSSIBLE; else no test number should be extracted at that leniency level
-         */
+        /// <summary>
+        /// Helper method which tests the contexts provided and ensures that:
+        /// -- if isValid is true, they all find a test number inserted in the middle when leniency of
+        ///  matching is set to VALID; else no test number should be extracted at that leniency level
+        /// -- if isPossible is true, they all find a test number inserted in the middle when leniency of
+        ///  matching is set to POSSIBLE; else no test number should be extracted at that leniency level
+        /// </summary>
         private void FindMatchesInContexts(List<NumberContext> contexts, bool isValid,
                                            bool isPossible, string region, string number)
         {
@@ -673,9 +673,9 @@ private void FindMatchesInContexts(List<NumberContext> contexts, bool isValid,
             }
         }
 
-        /**
-         * Variant of FindMatchesInContexts that uses a default number and region.
-         */
+        /// <summary>
+        /// Variant of FindMatchesInContexts that uses a default number and region.
+        /// </summary>
         private void FindMatchesInContexts(List<NumberContext> contexts, bool isValid, bool isPossible)
         {
             const string region = "US";
@@ -861,10 +861,10 @@ public void TestSingleIteration()
             iterator.Dispose();
         }
 
-        /**
-        * Asserts that another number can be found in {@code text} starting at {@code index}, and that
-        * its corresponding range is {@code [start, end)}.
-        */
+        /// <summary>
+        /// Asserts that another number can be found in <c>text</c> starting at <c>index</c>, and that
+        /// its corresponding range is <c>[start, end)</c>.
+        /// </summary>
         [SuppressMessage("ReSharper", "UnusedParameter.Local")]
         private void AssertEqualRange(string text, int index, int start, int end)
         {
@@ -879,12 +879,11 @@ private void AssertEqualRange(string text, int index, int start, int end)
             matches.Dispose();
         }
 
-        /**
-        * Tests numbers found by {@link PhoneNumberUtil#FindNumbers(CharSequence, String)} in various
-        * textual contexts.
-        *
-        * @param number the number to test and the corresponding region code to use
-        */
+        /// <summary>
+        /// Tests numbers found by <see cref="PhoneNumberUtil.FindNumbers(string, string)"/> in various
+        /// textual contexts.
+        /// </summary>
+        /// <param name="number">the number to test and the corresponding region code to use</param>
 #if NET6_0_OR_GREATER
         private void DoTestFindInContext(string number, string? defaultCountry)
 #else
@@ -938,9 +937,9 @@ private void FindPossibleInContext(string number, string defaultCountry)
             DoTestInContext(number, defaultCountry, contextPairs, PhoneNumberUtil.Leniency.POSSIBLE);
         }
 
-        /**
-        * Tests valid numbers in contexts that fail for {@link Leniency#POSSIBLE}.
-        */
+        /// <summary>
+        /// Tests valid numbers in contexts that fail for <see cref="PhoneNumberUtil.Leniency.POSSIBLE"/>.
+        /// </summary>
 #if NET6_0_OR_GREATER
         private void FindValidInContext(string number, string? defaultCountry)
 #else
@@ -987,10 +986,10 @@ private void DoTestInContext(string number, string defaultCountry, List<NumberCo
             }
         }
 
-        /**
-        * Exhaustively searches for phone numbers from each index within {@code text} to test that
-        * finding matches always terminates.
-        */
+        /// <summary>
+        /// Exhaustively searches for phone numbers from each index within <c>text</c> to test that
+        /// finding matches always terminates.
+        /// </summary>
 #if NET6_0_OR_GREATER
         private void EnsureTermination(string text, string? defaultCountry, PhoneNumberUtil.Leniency leniency)
 #else
@@ -1013,18 +1012,18 @@ private IEnumerable<PhoneNumberMatch> FindNumbersForLeniency(
             return phoneUtil.FindNumbers(text, defaultCountry, leniency, long.MaxValue);
         }
 
-        /**
-        * Returns true if there were no matches found.
-        */
+        /// <summary>
+        /// Returns true if there were no matches found.
+        /// </summary>
         private bool HasNoMatches(IEnumerable<PhoneNumberMatch> iterable)
         {
             return !iterable.GetEnumerator().MoveNext();
         }
 
-        /**
-        * Small class that holds the context of the number we are testing against. The test will
-        * insert the phone number to be found between leadingText and trailingText.
-        */
+        /// <summary>
+        /// Small class that holds the context of the number we are testing against. The test will
+        /// insert the phone number to be found between leadingText and trailingText.
+        /// </summary>
         private class NumberContext
         {
             public readonly string LeadingText;
@@ -1037,9 +1036,9 @@ public NumberContext(string leadingText, string trailingText)
             }
         }
 
-        /**
-           * Small class that holds the number we want to test and the region for which it should be valid.
-           */
+        /// <summary>
+        /// Small class that holds the number we want to test and the region for which it should be valid.
+        /// </summary>
         private class NumberTest
         {
             public readonly string RawString;