Add comments to URL lib.

c++/src/kj/compat/url-test.c++

@@ -272,14 +272,15 @@ KJ_TEST("URL relative paths") {
 KJ_TEST("URL for HTTP request") {
   {
     Url url = Url::parse("https://bob:1234@capnproto.org/foo/bar?baz=qux#corge");
-    KJ_EXPECT(url.toString(Url::GENERAL) == "https://bob:1234@capnproto.org/foo/bar?baz=qux#corge");
+    KJ_EXPECT(url.toString(Url::REMOTE_HREF) ==
+        "https://bob:1234@capnproto.org/foo/bar?baz=qux#corge");
     KJ_EXPECT(url.toString(Url::HTTP_PROXY_REQUEST) == "https://capnproto.org/foo/bar?baz=qux");
     KJ_EXPECT(url.toString(Url::HTTP_REQUEST) == "/foo/bar?baz=qux");
   }
 
   {
     Url url = Url::parse("https://capnproto.org");
-    KJ_EXPECT(url.toString(Url::GENERAL) == "https://capnproto.org");
+    KJ_EXPECT(url.toString(Url::REMOTE_HREF) == "https://capnproto.org");
     KJ_EXPECT(url.toString(Url::HTTP_PROXY_REQUEST) == "https://capnproto.org");
     KJ_EXPECT(url.toString(Url::HTTP_REQUEST) == "/");
   }

c++/src/kj/compat/url.c++

@@ -148,7 +148,7 @@ Maybe<Url> Url::tryParse(StringPtr text, Context context) {
       auto authority = split(text, END_AUTHORITY);
 
       KJ_IF_MAYBE(userpass, trySplit(authority, '@')) {
-        if (context != GENERAL) {
+        if (context != REMOTE_HREF) {
           // No user/pass allowed here.
           return nullptr;
         }
@@ -210,7 +210,7 @@ Maybe<Url> Url::tryParse(StringPtr text, Context context) {
   }
 
   if (text.startsWith("#")) {
-    if (context != GENERAL) {
+    if (context != REMOTE_HREF) {
       // No fragment allowed here.
       return nullptr;
     }
@@ -376,7 +376,7 @@ String Url::toString(Context context) const {
     chars.addAll(scheme);
     chars.addAll(StringPtr("://"));
 
-    if (context == GENERAL) {
+    if (context == REMOTE_HREF) {
       KJ_IF_MAYBE(user, userInfo) {
         chars.addAll(encodeUriComponent(user->username));
         KJ_IF_MAYBE(pass, user->password) {
@@ -422,7 +422,7 @@ String Url::toString(Context context) const {
     }
   }
 
-  if (context == GENERAL) {
+  if (context == REMOTE_HREF) {
     KJ_IF_MAYBE(f, fragment) {
       chars.add('#');
       chars.addAll(encodeUriComponent(*f));

c++/src/kj/compat/url.h

@@ -28,6 +28,10 @@
 namespace kj {
 
 struct Url {
+  // Represents a URL (or, more accurately, a URI, but whatever).
+  //
+  // Can be parsed from a string and composed back into a string.
+
   String scheme;
   // E.g. "http", "https".
 
@@ -69,8 +73,9 @@ struct Url {
   Url clone() const;
 
   enum Context {
-    GENERAL,
-    // The full URL.
+    REMOTE_HREF,
+    // A link to a remote resource. Requires an authority (hostname) section, hence this will
+    // reject things like "mailto:" and "data:". This is the default context.
 
     HTTP_PROXY_REQUEST,
     // The URL to place in the first line of an HTTP proxy request. This includes scheme, host,
@@ -80,13 +85,16 @@ struct Url {
     HTTP_REQUEST
     // The path to place in the first line of a regular HTTP request. This includes only the path
     // and query. Scheme, user, host, and fragment are omitted.
+
+    // TODO(someday): Add context(s) that supports things like "mailto:", "data:", "blob:". These
+    //   don't have an authority section.
   };
 
-  kj::String toString(Context context = GENERAL) const;
+  kj::String toString(Context context = REMOTE_HREF) const;
   // Convert the URL to a string.
 
-  static Url parse(StringPtr text, Context context = GENERAL);
-  static Maybe<Url> tryParse(StringPtr text, Context context = GENERAL);
+  static Url parse(StringPtr text, Context context = REMOTE_HREF);
+  static Maybe<Url> tryParse(StringPtr text, Context context = REMOTE_HREF);
   // Parse an absolute URL.
 
   Url parseRelative(StringPtr relative) const;