Doc update for parse method as suggested in issue #1218

Points people at parseAndKeepRawInput where appropriate.

cpp/src/phonenumbers/phonenumberutil.h

@@ -658,7 +658,15 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
   // a particular region is not performed. This can be done separately with
   // IsValidNumber().
   //
-  // number_to_parse can also be provided in RFC3966 format.
+  // Note this method canonicalizes the phone number such that different
+  // representations can be easily compared, no matter what form it was
+  // originally entered in (e.g. national, international). If you want to record
+  // context about the number being parsed, such as the raw input that was
+  // entered, how the country code was derived etc. then call
+  // ParseAndKeepRawInput() instead.
+  //
+  // number_to_parse can contain formatting such as +, ( and -, as well as a
+  // phone number extension. It can also be provided in RFC3966 format.
   //
   // default_region represents the country that we are expecting the number to
   // be from. This is only used if the number being parsed is not written in

java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

@@ -3018,6 +3018,12 @@ public class PhoneNumberUtil {
    * is actually a valid number for a particular region is not performed. This can be done
    * separately with {@link #isValidNumber}.
    *
+   * <p> Note this method canonicalizes the phone number such that different representations can be
+   * easily compared, no matter what form it was originally entered in (e.g. national,
+   * international). If you want to record context about the number being parsed, such as the raw
+   * input that was entered, how the country code was derived etc. then call {@link
+   * #parseAndKeepRawInput} instead.
+   *
    * @param numberToParse  number that we are attempting to parse. This can contain formatting such
    *     as +, ( and -, as well as a phone number extension. It can also be provided in RFC3966
    *     format.

javascript/i18n/phonenumbers/phonenumberutil.js

@@ -3977,6 +3977,12 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.checkRegionForParsing_ = function(
  * convert any alpha characters into digits if it thinks this is a vanity number
  * of the type "1800 MICROSOFT".
  *
+ * Note this method canonicalizes the phone number such that different
+ * representations can be easily compared, no matter what form it was originally
+ * entered in (e.g. national, international). If you want to record context
+ * about the number being parsed, such as the raw input that was entered, how
+ * the country code was derived etc. then call parseAndKeepRawInput() instead.
+ *
  * This method will throw a {@link i18n.phonenumbers.Error} if the number is not
  * considered to be a possible number. Note that validation of whether the
  * number is actually a valid number for a particular region is not performed.

pending_code_changes.txt

@@ -10,3 +10,5 @@ Code changes:
  - Bug fix for Javascript: getNationalSignificantNumber used to print the string
    "null" for empty phone number objects, now it returns an empty string.
  - Updated the documentation for the isNumberGeographical API.
+ - Small comment improvements for parse() method to point users at
+   parseAndKeepRawInput().