More Search-related PhpDoc additions

Summary: I'm still trying to understand search a bit better. As a side effect I add PhpDocs.

Test Plan: Inspect parameter and return formats, types, content while searching in Phorge.

Reviewers: O1 Blessed Committers, valerio.bozzolan

Reviewed By: O1 Blessed Committers, valerio.bozzolan

Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Differential Revision: https://we.phorge.it/D26042

src/applications/search/engineextension/PhabricatorSearchEngineExtension.php

@@ -5,6 +5,10 @@ abstract class PhabricatorSearchEngineExtension extends Phobject {
   private $viewer;
   private $searchEngine;
 
+  /**
+   * @return string The EXTENSIONKEY of the PhabricatorSearchEngineExtension
+   *   subclass
+   */
   final public function getExtensionKey() {
     return $this->getPhobjectClassConstant('EXTENSIONKEY');
   }
@@ -14,6 +18,9 @@ abstract class PhabricatorSearchEngineExtension extends Phobject {
     return $this;
   }
 
+  /**
+   * @return PhabricatorUser
+   */
   final public function getViewer() {
     return $this->viewer;
   }
@@ -24,22 +31,43 @@ abstract class PhabricatorSearchEngineExtension extends Phobject {
     return $this;
   }
 
+  /**
+   * @return PhabricatorApplicationSearchEngine A subclass of
+   *   PhabricatorApplicationSearchEngine
+   */
   final public function getSearchEngine() {
     return $this->searchEngine;
   }
 
+  /**
+   * @return bool
+   */
   abstract public function isExtensionEnabled();
+  /**
+   * @return string  Description of the Search Engine Extension
+   */
   abstract public function getExtensionName();
+  /**
+   * @return bool
+   */
   abstract public function supportsObject($object);
 
   public function getExtensionOrder() {
     return 7000;
   }
 
+  /**
+   * @return array<PhabricatorSearchField> Subclasses of
+   *   PhabricatorSearchField, or an empty array
+   */
   public function getSearchFields($object) {
     return array();
   }
 
+  /**
+   * @return array<PhabricatorSearchEngineAttachment> Subclasses of
+   *   PhabricatorSearchEngineAttachment, or an empty array
+   */
   public function getSearchAttachments($object) {
     return array();
   }
@@ -64,6 +92,11 @@ abstract class PhabricatorSearchEngineExtension extends Phobject {
     return array();
   }
 
+  /**
+   * @return map<string, PhabricatorSearchEngineExtension> Array of
+   *   PhabricatorSearchEngineExtension extension keys and the
+   *   PhabricatorSearchEngineExtension subclasses
+   */
   final public static function getAllExtensions() {
     return id(new PhutilClassMapQuery())
       ->setAncestorClass(__CLASS__)

src/applications/search/ferret/PhabricatorFerretEngine.php

@@ -6,8 +6,18 @@ abstract class PhabricatorFerretEngine extends Phobject {
   private $ferretFunctions;
   private $templateObject;
 
+  /**
+   * @return string Application name in lower-case, e.g. 'maniphest'
+   */
   abstract public function getApplicationName();
+  /**
+   * @return string Object name in lower-case, e.g. 'task'
+   */
   abstract public function getScopeName();
+  /**
+   * @return string New instance of the corresponding
+   *   PhabricatorApplicationSearchEngine subclass
+   */
   abstract public function newSearchEngine();
 
   public function getDefaultFunctionKey() {
@@ -47,10 +57,16 @@ abstract class PhabricatorFerretEngine extends Phobject {
     return $this->fieldMap[$raw_name];
   }
 
+  /**
+   * @return PhutilSearchStemmer New instance of PhutilSearchStemmer
+   */
   public function newStemmer() {
     return new PhutilSearchStemmer();
   }
 
+  /**
+   * @return string
+   */
   public function newTermsCorpus($raw_corpus) {
     $term_corpus = strtr(
       $raw_corpus,
@@ -108,6 +124,10 @@ abstract class PhabricatorFerretEngine extends Phobject {
 
 /* -(  Schema  )------------------------------------------------------------- */
 
+  /**
+   * @return string Name of database table, e.g. 'calendar_event_fdocument' or
+   *   'maniphest_task_fdocument' or 'phame_post_fdocument'
+   */
   public function getDocumentTableName() {
     $application = $this->getApplicationName();
     $scope = $this->getScopeName();
@@ -152,6 +172,10 @@ abstract class PhabricatorFerretEngine extends Phobject {
     );
   }
 
+  /**
+   * @return string Name of database table, e.g. 'calendar_event_ffield' or
+   *   'maniphest_task_ffield' or 'phame_post_ffield'
+   */
   public function getFieldTableName() {
     $application = $this->getApplicationName();
     $scope = $this->getScopeName();
@@ -183,6 +207,10 @@ abstract class PhabricatorFerretEngine extends Phobject {
     );
   }
 
+  /**
+   * @return string Name of database table, e.g. 'calendar_event_fngrams' or
+   *   'maniphest_task_fngrams' or 'phame_post_fngrams'
+   */
   public function getNgramsTableName() {
     $application = $this->getApplicationName();
     $scope = $this->getScopeName();
@@ -213,6 +241,11 @@ abstract class PhabricatorFerretEngine extends Phobject {
     );
   }
 
+  /**
+   * @return string Name of database table, e.g.
+   *   'calendar_event_fngrams_common' or 'maniphest_task_fngrams_common' or
+   *   'phame_post_fngrams_common'
+   */
   public function getCommonNgramsTableName() {
     $application = $this->getApplicationName();
     $scope = $this->getScopeName();

src/applications/search/ferret/PhabricatorFerretMetadata.php

@@ -11,6 +11,10 @@ final class PhabricatorFerretMetadata extends Phobject {
     return $this;
   }
 
+  /**
+   * @return PhabricatorFerretEngine A subclass of PhabricatorFerretEngine,
+   *   e.g. DiffusionCommitFerretEngine or ManiphestTaskFerretEngine
+   */
   public function getEngine() {
     return $this->engine;
   }
@@ -20,6 +24,9 @@ final class PhabricatorFerretMetadata extends Phobject {
     return $this;
   }
 
+  /**
+   * @return string PHID of a search result
+   */
   public function getPHID() {
     return $this->phid;
   }
@@ -29,10 +36,16 @@ final class PhabricatorFerretMetadata extends Phobject {
     return $this;
   }
 
+  /**
+   * @return int
+   */
   public function getRelevance() {
     return $this->relevance;
   }
 
+  /**
+   * @return PhutilSortVector
+   */
   public function getRelevanceSortVector() {
     $engine = $this->getEngine();
 

src/applications/search/ferret/function/FerretSearchFunction.php

@@ -3,14 +3,34 @@
 abstract class FerretSearchFunction
   extends Phobject {
 
+  /**
+   * @return string Ferret function name, e.g. 'title', 'body', 'comment',
+   *   'core', 'all'
+   */
   abstract public function getFerretFunctionName();
+  /**
+   * @return string Ferret field key, e.g. 'titl', 'body', 'cmnt', 'core',
+   *   'full'
+   */
   abstract public function getFerretFieldKey();
+  /**
+   * @return bool
+   */
   abstract public function supportsObject(PhabricatorFerretInterface $object);
 
+  /**
+   * @param  string $name
+   * @return string Lower-case $name
+   */
   final public static function getNormalizedFunctionName($name) {
     return phutil_utf8_strtolower($name);
   }
 
+  /**
+   * @param string $function_name
+   * @return void
+   * @throws Exception if $function_name is invalid
+   */
   final public static function validateFerretFunctionName($function_name) {
     if (!preg_match('/^[a-zA-Z-]+\z/', $function_name)) {
       throw new Exception(
@@ -22,6 +42,12 @@ abstract class FerretSearchFunction
     }
   }
 
+  /**
+   * @param string $field_key Ferret search engine field key, supposed to be
+   *   four characters and only lowercase latin letters
+   * @return void
+   * @throws Exception if $field_key is invalid
+   */
   final public static function validateFerretFunctionFieldKey($field_key) {
     if (!preg_match('/^[a-z]{4}\z/', $field_key)) {
       throw new Exception(
@@ -33,6 +59,9 @@ abstract class FerretSearchFunction
     }
   }
 
+  /**
+   * @return array<string,FerretSearchFunction>
+   */
   final public static function newFerretSearchFunctions() {
     $extensions = PhabricatorFulltextEngineExtension::getAllExtensions();