doc update

docs/parsers/url.md

@@ -5,6 +5,13 @@
 
 jc - JSON Convert URL string parser
 
+Normalized, Encoded, and Decoded versions of the original URL and URL parts
+are included in the output. Encoding and Decoding is best effort.
+
+> Note: Do not use the Encoded fields for a URL that has already been
+> Encoded. Similarly, do not use the Decoded fields for a URL that has
+> already been Decoded.
+
 This parser will work with naked and wrapped URL strings:
 
 - `scheme://host/path`
@@ -12,13 +19,6 @@ This parser will work with naked and wrapped URL strings:
 - `<scheme://host/path>`
 - `<URL:scheme://host/path>`
 
-Normalized, Encoded, and Decoded versions of the original URL and URL parts
-are included in the output.
-
-> Note: Do not use the encoded fields for a URL that has already been
-> encoded. Similarly, do not use the decoded fields for a URL that has
-> already been decoded.
-
 Usage (cli):
 
     $ echo "http://example.com/test/path?q1=foo&q2=bar#frag" | jc --url
@@ -48,7 +48,7 @@ Schema:
       "username":                  string or null,
       "password":                  string or null,
       "hostname":                  string or null,
-      "port":                      integer or null,
+      "port":                      integer or null,  # [1]
       "encoded": {
         "url":                     string,
         "scheme":                  string,
@@ -62,7 +62,7 @@ Schema:
         "username":                string or null,
         "password":                string or null,
         "hostname":                string or null,
-        "port":                    string or null,
+        "port":                    integer or null,  # [1]
       },
       "decoded": {
         "url":                     string,
@@ -77,13 +77,16 @@ Schema:
         "username":                string or null,
         "password":                string or null,
         "hostname":                string or null,
-        "port":                    string or null,
+        "port":                    integer or null,  # [1]
       }
     }
 
     [0] Duplicate query-keys will have their values consolidated into the
         array of query-values
 
+    [1] Invalid port values will be converted to null/None and a warning
+        message will be printed to `STDERR` if quiet=False
+
 Examples:
 
     % echo "http://example.com/test/path?q1=foo&q1=bar&q2=baz#frag" \\