RDAP: Document RDAP guidance

Updates the RDAP code to reflect guidance and confirmation received from various mailing lists.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=129254894

java/google/registry/rdap/RdapEntityAction.java

@@ -66,6 +66,8 @@ public class RdapEntityAction extends RdapActionBase {
       wasValidKey = true;
       Key<ContactResource> contactKey = Key.create(ContactResource.class, pathSearchString);
       ContactResource contactResource = ofy().load().key(contactKey).now();
+      // As per Andy Newton on the regext mailing list, contacts by themselves have no role, since
+      // they are global, and might have different roles for different domains.
       if ((contactResource != null) && clock.nowUtc().isBefore(contactResource.getDeletionTime())) {
         return RdapJsonFormatter.makeRdapJsonForContact(
             contactResource,

java/google/registry/rdap/RdapEntitySearchAction.java

@@ -86,6 +86,14 @@ public class RdapEntitySearchAction extends RdapActionBase {
     ImmutableList<ImmutableMap<String, Object>> results;
     if (fnParam.isPresent()) {
       // syntax: /rdap/entities?fn=Bobby%20Joe*
+      // TODO(b/25973399): implement entity name search, and move the comment below to that routine
+      // As per Gustavo Lozano of ICANN, registrar name search should be by registrar name only, not
+      // by registrar contact name:
+      //
+      //   The search is by registrar name only. The profile is supporting the functionality defined
+      //   in the Base Registry Agreement (see 1.6 of Section 4 of the Base Registry Agreement,
+      //   https://newgtlds.icann.org/sites/default/files/agreements/
+      //   agreement-approved-09jan14-en.htm).
       throw new NotImplementedException("Entity name search not implemented");
     } else {
       // syntax: /rdap/entities?handle=12345-*
@@ -113,6 +121,8 @@ public class RdapEntitySearchAction extends RdapActionBase {
       Registrar registrar = Registrar.loadByClientId(partialStringQuery.getInitialString());
       ImmutableList.Builder<ImmutableMap<String, Object>> builder = new ImmutableList.Builder<>();
       if ((contactResource != null) && contactResource.getDeletionTime().isEqual(END_OF_TIME)) {
+        // As per Andy Newton on the regext mailing list, contacts by themselves have no role, since
+        // they are global, and might have different roles for different domains.
         builder.add(RdapJsonFormatter.makeRdapJsonForContact(
             contactResource,
             false,

java/google/registry/rdap/RdapJsonFormatter.java

@@ -836,6 +836,23 @@ public class RdapJsonFormatter {
     ImmutableList.Builder<Object> builder = new ImmutableList.Builder<>();
     builder.add(""); // PO box
     builder.add(""); // extended address
+
+    // The vCard spec allows several different ways to handle multiline street addresses. Per
+    // Gustavo Lozano of ICANN, the one we should use is an embedded array of street address lines
+    // if there is more than one line:
+    //
+    //   RFC7095 provides two examples of structured addresses, and one of the examples shows a
+    //   street JSON element that contains several data elements. The example showing (see below)
+    //   several data elements is the expected output when two or more <contact:street> elements
+    //   exists in the contact object.
+    //
+    //   ["adr", {}, "text",
+    //    [
+    //    "", "",
+    //    ["My Street", "Left Side", "Second Shack"],
+    //    "Hometown", "PA", "18252", "U.S.A."
+    //    ]
+    //   ]
     ImmutableList<String> street = address.getStreet();
     if (street.isEmpty()) {
       builder.add("");