Update documentation for IsValidNumber method (#1460)

cpp/src/phonenumbers/phonenumberutil.h

@@ -386,6 +386,12 @@ class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
   // Tests whether a phone number matches a valid pattern. Note this doesn't
   // verify the number is actually in use, which is impossible to tell by just
   // looking at a number itself.
+  // It only verifies whether the parsed, canonicalised number is valid: not
+  // whether a particular series of digits entered by the user is diallable from
+  // the region provided when parsing. For example, the number +41 (0) 78 927
+  // 2696 can be parsed into a number with country code "41" and national
+  // significant number "789272696". This is valid, while the original string
+  // is not diallable.
   bool IsValidNumber(const PhoneNumber& number) const;
 
   // Tests whether a phone number is valid for a certain region. Note this

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

@@ -2135,7 +2135,11 @@ public class PhoneNumberUtil {
 
   /**
    * Tests whether a phone number matches a valid pattern. Note this doesn't verify the number
-   * is actually in use, which is impossible to tell by just looking at a number itself.
+   * is actually in use, which is impossible to tell by just looking at a number itself. It only
+   * verifies whether the parsed, canonicalised number is valid: not whether a particular series of
+   * digits entered by the user is diallable from the region provided when parsing. For example, the
+   * number +41 (0) 78 927 2696 can be parsed into a number with country code "41" and national
+   * significant number "789272696". This is valid, while the original string is not diallable.
    *
    * @param number  the phone number that we want to validate
    * @return  a boolean that indicates whether the number is of a valid pattern

javascript/i18n/phonenumbers/phonenumberutil.js

@@ -2806,6 +2806,12 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.isNumberMatchingDesc_ =
  * Tests whether a phone number matches a valid pattern. Note this doesn't
  * verify the number is actually in use, which is impossible to tell by just
  * looking at a number itself.
+ * It only verifies whether the parsed, canonicalised number is valid: not
+ * whether a particular series of digits entered by the user is diallable from
+ * the region provided when parsing. For example, the number +41 (0) 78 927 2696
+ * can be parsed into a number with country code "41" and national significant
+ * number "789272696". This is valid, while the original string is not
+ * diallable.
  *
  * @param {i18n.phonenumbers.PhoneNumber} number the phone number that we want
  *     to validate.