Minor tidying of DivinerAtom and DivinerAtomRef

Summary: Self-explanatory.

Test Plan: Eyeball it.

Reviewers: epriestley, #blessed_reviewers

Reviewed By: epriestley, #blessed_reviewers

Subscribers: Korvin, epriestley

Differential Revision: https://secure.phabricator.com/D11592

src/applications/diviner/atom/DivinerAtom.php

@@ -2,12 +2,12 @@
 
 final class DivinerAtom {
 
-  const TYPE_FILE      = 'file';
   const TYPE_ARTICLE   = 'article';
-  const TYPE_METHOD    = 'method';
   const TYPE_CLASS     = 'class';
+  const TYPE_FILE      = 'file';
   const TYPE_FUNCTION  = 'function';
   const TYPE_INTERFACE = 'interface';
+  const TYPE_METHOD    = 'method';
 
   private $type;
   private $name;
@@ -95,14 +95,16 @@ final class DivinerAtom {
 
   public function getDocblockText() {
     if ($this->docblockText === null) {
-      throw new Exception('Call setDocblockRaw() before getDocblockText()!');
+      throw new Exception(
+        pht('Call %s before %s!', 'setDocblockRaw()', 'getDocblockText()'));
     }
     return $this->docblockText;
   }
 
   public function getDocblockMeta() {
     if ($this->docblockMeta === null) {
-      throw new Exception('Call setDocblockRaw() before getDocblockMeta()!');
+      throw new Exception(
+        pht('Call %s before %s!', 'setDocblockRaw()', 'getDocblockMeta()'));
     }
     return $this->docblockMeta;
   }
@@ -248,7 +250,7 @@ final class DivinerAtom {
 
   public function setParentHash($parent_hash) {
     if ($this->parentHash) {
-      throw new Exception('Atom already has a parent!');
+      throw new Exception(pht('Atom already has a parent!'));
     }
     $this->parentHash = $parent_hash;
     return $this;
@@ -260,7 +262,7 @@ final class DivinerAtom {
 
   public function setParent(DivinerAtom $atom) {
     if ($this->parentHash) {
-      throw new Exception('Parent hash has already been computed!');
+      throw new Exception(pht('Parent hash has already been computed!'));
     }
     $this->parent = $atom;
     return $this;
@@ -275,7 +277,7 @@ final class DivinerAtom {
 
   public function addChild(DivinerAtom $atom) {
     if ($this->childHashes) {
-      throw new Exception('Child hashes have already been computed!');
+      throw new Exception(pht('Child hashes have already been computed!'));
     }
 
     $atom->setParent($this);
@@ -294,11 +296,9 @@ final class DivinerAtom {
     return implode('/', $parts);
   }
 
-
   public function toDictionary() {
     // NOTE: If you change this format, bump the format version in
-    // getAtomSerializationVersion().
+    // @{method:getAtomSerializationVersion}.
-
     return array(
       'book'        => $this->getBook(),
       'type'        => $this->getType(),
@@ -385,18 +385,18 @@ final class DivinerAtom {
 
   public static function getThisAtomIsNotDocumentedString($type) {
     switch ($type) {
+      case self::TYPE_ARTICLE:
+        return pht('This article is not documented.');
+      case self::TYPE_CLASS:
+        return pht('This class is not documented.');
       case self::TYPE_FILE:
         return pht('This file is not documented.');
       case self::TYPE_FUNCTION:
         return pht('This function is not documented.');
-      case self::TYPE_CLASS:
-        return pht('This class is not documented.');
-      case self::TYPE_ARTICLE:
-        return pht('This article is not documented.');
-      case self::TYPE_METHOD:
-        return pht('This method is not documented.');
       case self::TYPE_INTERFACE:
         return pht('This interface is not documented.');
+      case self::TYPE_METHOD:
+        return pht('This method is not documented.');
       default:
         phlog("Need translation for '{$type}'.");
         return pht('This %s is not documented.', $type);
@@ -405,29 +405,29 @@ final class DivinerAtom {
 
   public static function getAllTypes() {
     return array(
+      self::TYPE_ARTICLE,
+      self::TYPE_CLASS,
       self::TYPE_FILE,
       self::TYPE_FUNCTION,
-      self::TYPE_CLASS,
-      self::TYPE_ARTICLE,
-      self::TYPE_METHOD,
       self::TYPE_INTERFACE,
+      self::TYPE_METHOD,
     );
   }
 
   public static function getAtomTypeNameString($type) {
     switch ($type) {
+      case self::TYPE_ARTICLE:
+        return pht('Article');
+      case self::TYPE_CLASS:
+        return pht('Class');
       case self::TYPE_FILE:
         return pht('File');
       case self::TYPE_FUNCTION:
         return pht('Function');
-      case self::TYPE_CLASS:
-        return pht('Class');
-      case self::TYPE_ARTICLE:
-        return pht('Article');
-      case self::TYPE_METHOD:
-        return pht('Method');
       case self::TYPE_INTERFACE:
         return pht('Interface');
+      case self::TYPE_METHOD:
+        return pht('Method');
       default:
         phlog("Need translation for '{$type}'.");
         return ucwords($type);

src/applications/diviner/atom/DivinerAtomRef.php

@@ -43,10 +43,12 @@ final class DivinerAtomRef {
 
   public function setName($name) {
     $normal_name = self::normalizeString($name);
-    if (preg_match('/^@[0-9]+\z/', $normal_name)) {
+    if (preg_match('/^@\d+\z/', $normal_name)) {
       throw new Exception(
-        "Atom names must not be in the form '/@\d+/'. This pattern is ".
+        pht(
-        "reserved for disambiguating atoms with similar names.");
+          "Atom names must not be in the form '%s'. This pattern is ".
+          "reserved for disambiguating atoms with similar names.",
+          '/@\d+/'));
     }
     $this->name = $normal_name;
     return $this;
@@ -120,8 +122,8 @@ final class DivinerAtomRef {
       'type'    => $this->getType(),
       'name'    => $this->getName(),
       'group'   => $this->getGroup(),
-      'index'   => $this->getIndex(),
       'summary' => $this->getSummary(),
+      'index'   => $this->getIndex(),
       'title'   => $this->getTitle(),
     );
   }
@@ -139,46 +141,44 @@ final class DivinerAtomRef {
   }
 
   public static function newFromDictionary(array $dict) {
-    $obj = new DivinerAtomRef();
+    return id(new DivinerAtomRef())
-    $obj->setBook(idx($dict, 'book'));
+      ->setBook(idx($dict, 'book'))
-    $obj->setContext(idx($dict, 'context'));
+      ->setContext(idx($dict, 'context'))
-    $obj->setType(idx($dict, 'type'));
+      ->setType(idx($dict, 'type'))
-    $obj->setName(idx($dict, 'name'));
+      ->setName(idx($dict, 'name'))
-    $obj->group = idx($dict, 'group');
+      ->setGroup(idx($dict, 'group'))
-    $obj->index = idx($dict, 'index');
+      ->setSummary(idx($dict, 'summary'))
-    $obj->summary = idx($dict, 'summary');
+      ->setIndex(idx($dict, 'index'))
-    $obj->title = idx($dict, 'title');
+      ->setTitle(idx($dict, 'title'));
-
-    return $obj;
   }
 
   public static function normalizeString($str) {
     // These characters create problems on the filesystem or in URIs. Replace
-    // them with non-problematic appoximations (instead of simply removing them)
+    // them with non-problematic approximations (instead of simply removing
-    // to keep the URIs fairly useful and avoid unnecessary collisions. These
+    // them) to keep the URIs fairly useful and avoid unnecessary collisions.
-    // approximations are selected based on some domain knowledge of common
+    // These approximations are selected based on some domain knowledge of
-    // languages: where a character is used as a delimiter, it is more helpful
+    // common languages: where a character is used as a delimiter, it is more
-    // to replace it with a "." or a ":" or similar, while it's better if
+    // helpful to replace it with a "." or a ":" or similar, while it's better
-    // operator overloads read as, e.g., "operator_div".
+    // if operator overloads read as, e.g., "operator_div".
 
     $map = array(
       // Hopefully not used anywhere by anything.
-      '#'   => '.',
+      '#' => '.',
 
       // Used in Ruby methods.
-      '?'   => 'Q',
+      '?' => 'Q',
 
       // Used in PHP namespaces.
-      '\\'  => '.',
+      '\\' => '.',
 
       // Used in "operator +" in C++.
-      '+'   => 'plus',
+      '+' => 'plus',
 
       // Used in "operator %" in C++.
-      '%'   => 'mod',
+      '%' => 'mod',
 
       // Used in "operator /" in C++.
-      '/'   => 'div',
+      '/' => 'div',
     );
     $str = str_replace(array_keys($map), array_values($map), $str);
 
@@ -190,9 +190,9 @@ final class DivinerAtomRef {
 
     // Replace specific problematic names with alternative names.
     $alternates = array(
-      '.'   => 'dot',
+      '.'  => 'dot',
-      '..'  => 'dotdot',
+      '..' => 'dotdot',
-      ''    => 'null',
+      ''   => 'null',
     );
 
     return idx($alternates, $str, $str);