Bring PackageSpecification docs up-to-date, clean up its interface

Focuses on documenting the Strings that PackageSpecifications can be
translated from and to.

--
MOS_MIGRATED_REVID=128195540
diff --git a/src/test/java/com/google/devtools/build/lib/packages/PackageGroupStaticInitializationTest.java b/src/test/java/com/google/devtools/build/lib/packages/PackageGroupStaticInitializationTest.java
index 8f993ab..404b7aa 100644
--- a/src/test/java/com/google/devtools/build/lib/packages/PackageGroupStaticInitializationTest.java
+++ b/src/test/java/com/google/devtools/build/lib/packages/PackageGroupStaticInitializationTest.java
@@ -16,18 +16,17 @@
 import static org.junit.Assert.assertFalse;
 
 import com.google.devtools.build.lib.cmdline.Label;
+import com.google.devtools.build.lib.cmdline.RepositoryName;
 import com.google.devtools.build.lib.events.util.EventCollectionApparatus;
 import com.google.devtools.build.lib.packages.util.PackageFactoryApparatus;
 import com.google.devtools.build.lib.testutil.Scratch;
 import com.google.devtools.build.lib.vfs.Path;
 import com.google.devtools.build.lib.vfs.PathFragment;
-
+import java.util.concurrent.SynchronousQueue;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
 
-import java.util.concurrent.SynchronousQueue;
-
 /**
  * Checks against a class initialization deadlock. "query sometimes hangs".
  *
@@ -51,8 +50,11 @@
               @Override
               public void run() {
                 try {
-                  groupQueue.put(PackageSpecification.fromString(
-                      Label.parseAbsoluteUnchecked("//context"), "//fruits/..."));
+                  RepositoryName defaultRepoName =
+                      Label.parseAbsoluteUnchecked("//context")
+                          .getPackageIdentifier()
+                          .getRepository();
+                  groupQueue.put(PackageSpecification.fromString(defaultRepoName, "//fruits/..."));
                 } catch (Exception e) {
                   // Can't throw from Runnable, but this will cause the test to timeout
                   // when the consumer can't take the object.
diff --git a/src/test/java/com/google/devtools/build/lib/packages/PackageGroupTest.java b/src/test/java/com/google/devtools/build/lib/packages/PackageGroupTest.java
index 24002f2..50ca268 100644
--- a/src/test/java/com/google/devtools/build/lib/packages/PackageGroupTest.java
+++ b/src/test/java/com/google/devtools/build/lib/packages/PackageGroupTest.java
@@ -23,7 +23,6 @@
 import com.google.devtools.build.lib.testutil.Scratch;
 import com.google.devtools.build.lib.vfs.Path;
 import com.google.devtools.build.lib.vfs.PathFragment;
-
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
@@ -151,7 +150,7 @@
     scratch.file("fruits/BUILD", "package_group(name = 'mango', packages = ['//...'])");
     PackageGroup packageGroup = getPackageGroup("fruits", "mango");
     assertThat(packageGroup.getPackageSpecifications())
-        .containsExactlyElementsIn(ImmutableList.of(PackageSpecification.EVERYTHING));
+        .containsExactlyElementsIn(ImmutableList.of(PackageSpecification.everything()));
   }
 
   private Package getPackage(String packageName) throws Exception {