Misc PhpDoc additions or improvements

Summary: Side effect of stuff I've been poking and trying to understand what it may do.

Test Plan: Check parameter and return types, read code.

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/D26512

src/applications/auth/controller/PhabricatorAuthController.php

···
 
 abstract class PhabricatorAuthController extends PhabricatorController {
 
+  /**
+   * @return PhabricatorStandardPageView PhabricatorStandardPageView with a
+   *  @{class:PHUIInfoView} child displaying error messages.
+   */
   protected function renderErrorPage($title, array $messages) {
     $view = new PHUIInfoView();
     $view->setTitle($title);
···
   }
 
   /**
-   * Returns true if this install is newly setup (i.e., there are no user
+   * Returns true if this install is newly set up (i.e., there are no user
    * accounts yet). In this case, we enter a special mode to permit creation
    * of the first account form the web UI.
+   *
+   * @return bool
    */
   protected function isFirstTimeSetup() {
     // If there are any auth providers, this isn't first time setup, even if
···
     $request->clearCookie(PhabricatorCookies::COOKIE_INVITE);
   }
 
+  /**
+   * @return AphrontRedirectResponse Redirect to /auth/validate/, including
+   *   an "expect" parameter with the expected username, to be validated in
+   *   @{class:PhabricatorAuthValidateController}
+   */
   private function buildLoginValidateResponse(PhabricatorUser $user) {
     $validate_uri = new PhutilURI($this->getApplicationURI('validate/'));
     $validate_uri->replaceQueryParam('expect', $user->getUsername());
···
       ));
   }
 
+  /**
+   * @return array Returns <null,null,PhabricatorStandardPageView> or
+   *   <PhabricatorExternalAccount,null,PhabricatorStandardPageView> in case of
+   *   an error, or <PhabricatorExternalAccount,PhabricatorAuthProvider,null>
+   *   in case of success.
+   */
   protected function loadAccountForRegistrationOrLinking($account_key) {
     $request = $this->getRequest();
     $viewer = $request->getUser();
···
     return array($account, $provider, null);
   }
 
+  /**
+   * @return PhabricatorAuthInvite|null Invitation, or null if none exists
+   */
   protected function loadInvite() {
     $invite_cookie = PhabricatorCookies::COOKIE_INVITE;
     $invite_code = $this->getRequest()->getCookie($invite_cookie);
···
     }
   }
 
+  /**
+   * @return PHUIBoxView|null
+   */
   protected function renderInviteHeader(PhabricatorAuthInvite $invite) {
     $viewer = $this->getViewer();
 
···
       ->appendChild($invite_list);
   }
 
-
+  /**
+   * @return PhutilSafeHTML|null
+   */
   final protected function newCustomStartMessage() {
     $viewer = $this->getViewer();
 

src/applications/auth/engine/PhabricatorAuthInviteEngine.php

···
     return $this->userHasConfirmedVerify;
   }
 
+  /**
+   * @return PhabricatorAuthInvite
+   */
   public function processInviteCode($code) {
     $viewer = $this->getViewer();
 

src/applications/base/controller/PhabricatorController.php

···
       ->setSubmitURI($submit_uri);
   }
 
+  /**
+   * @return AphrontRedirectResponse
+   */
   public function newRedirect() {
     return id(new AphrontRedirectResponse());
   }
 
+  /**
+   * @return PhabricatorStandardPageView
+   */
   public function newPage() {
     $page = id(new PhabricatorStandardPageView())
       ->setRequest($this->getRequest())
···
     return $page;
   }
 
+  /**
+   * @return PHUIApplicationMenuView
+   */
   public function newApplicationMenu() {
     return id(new PHUIApplicationMenuView())
       ->setViewer($this->getViewer());

src/applications/conduit/data/ConduitConstantDescription.php

···
   private $value;
   private $isDeprecated;
 
+  /**
+   * @param string $key Key of the constant
+   */
   public function setKey($key) {
     $this->key = $key;
     return $this;
···
     return $this->key;
   }
 
+  /**
+   * @param string $value Description of the constant
+   */
   public function setValue($value) {
     $this->value = $value;
     return $this;
···
     return $this->value;
   }
 
+  /**
+   * @param bool $is_deprecated Whether the constant is deprecated
+   */
   public function setIsDeprecated($is_deprecated) {
     $this->isDeprecated = $is_deprecated;
     return $this;

src/applications/conduit/method/ConduitAPIMethod.php

···
     return array();
   }
 
+  /**
+   * @return ConduitAPIDocumentationPage
+   */
   final protected function newDocumentationPage(PhabricatorUser $viewer) {
     return id(new ConduitAPIDocumentationPage())
       ->setIconIcon('fa-chevron-right');
   }
 
+  /**
+   * @return ConduitAPIDocumentationPage
+   */
   final protected function newDocumentationBoxPage(
     PhabricatorUser $viewer,
     $title,
···
   /**
    * Return a key which sorts methods by application name, then method status,
    * then method name.
+   *
+   * @return string For example 'almanac.0.namespace.edit' or 'user.2.enable'
    */
   public function getSortOrder() {
     $name = $this->getAPIMethodName();

src/applications/config/option/PhabricatorConfigOption.php

···
     return $this;
   }
 
+  /**
+   * @return array Pairs of a config value and its description
+   */
   public function getExamples() {
     return $this->examples;
   }
···
     return $this;
   }
 
+  /**
+   * @return array Array of boolean options, defaults to True and False
+   */
   public function getBoolOptions() {
     if ($this->boolOptions) {
       return $this->boolOptions;

src/applications/dashboard/engine/PhabricatorDashboardPanelRenderingEngine.php

···
     return $this->panelPHID;
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   public function renderPanel() {
     $panel = $this->getPanel();
 
···
       $header);
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   private function renderPanelDiv(
     $content,
     $header = null,

src/applications/home/engine/PhabricatorHomeProfileMenuEngine.php

···
     );
   }
 
+  /**
+   * Returns the menu items in the default home sidebar
+   *
+   * @return array<PhabricatorProfileMenuItemConfiguration>
+   */
   protected function getBuiltinProfileItems($object) {
     $viewer = $this->getViewer();
     $items = array();

src/applications/home/menuitem/PhabricatorHomeProfileMenuItem.php

···
     return $this->getDefaultName();
   }
 
+  /**
+   * @return PHUIHomeView
+   */
   public function newPageContent(
     PhabricatorProfileMenuItemConfiguration $config) {
     $viewer = $this->getViewer();
···
       ->setViewer($viewer);
   }
 
+  /**
+   * @return array<PhabricatorTextEditField>
+   */
   public function buildEditEngineFields(
     PhabricatorProfileMenuItemConfiguration $config) {
     return array(
···
     );
   }
 
+  /**
+   * @return array<PhabricatorProfileMenuItemView>
+   */
   protected function newMenuItemViewList(
     PhabricatorProfileMenuItemConfiguration $config) {
     $viewer = $this->getViewer();

src/applications/home/view/PHUIHomeView.php

···
     return array();
   }
 
+  /**
+   * Construct the default homepage dashboard.
+   *
+   * @return PHUIBoxView Homepage dashboard content: a PHUIBoxView which wraps
+   *  a @{class:AphrontMultiColumnView} which includes numerous
+   *  @{class:PHUIObjectBoxView} boxes
+   */
   protected function getTagContent() {
     require_celerity_resource('phabricator-dashboard-css');
     $viewer = $this->getViewer();
···
       return $view;
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   private function buildRevisionPanel() {
     $viewer = $this->getViewer();
     if (!$viewer->isLoggedIn()) {
···
     return $this->renderPanel($panel);
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   private function buildTasksPanel() {
     $viewer = $this->getViewer();
 
···
     return $this->renderPanel($panel);
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   public function buildFeedPanel() {
     $panel = $this->newQueryPanel()
       ->setName(pht('Recent Activity'))
···
     return $this->renderPanel($panel);
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   public function buildRepositoryPanel() {
     $panel = $this->newQueryPanel()
       ->setName(pht('Active Repositories'))
···
     return $this->renderPanel($panel);
   }
 
+  /**
+   * @return PhabricatorDashboardPanel
+   */
   private function newQueryPanel() {
     $panel_type = id(new PhabricatorDashboardQueryPanelType())
       ->getPanelTypeKey();
···
       ->setPanelType($panel_type);
   }
 
+  /**
+   * @return PHUIObjectBoxView
+   */
   private function renderPanel(PhabricatorDashboardPanel $panel) {
     $viewer = $this->getViewer();
 

src/applications/search/controller/PhabricatorApplicationSearchController.php

···
     return $menu;
   }
 
+  /**
+   * @return AphrontSideNavFilterView
+   */
   private function buildNavigation() {
     $viewer = $this->getViewer();
     $engine = $this->getSearchEngine();
···
     return $nav;
   }
 
+  /**
+   * Render a content body (if available) to onboard new users. This may return
+   * what the corresponding PhabricatorApplicationSearchEngine returns, or null
+   * based on some additional checks performed in this function.
+   *
+   * @return mixed|PhutilSafeHTML|null
+   */
   private function renderNewUserView(
     PhabricatorApplicationSearchEngine $engine,
     $force_nux) {
···
     return $nux_view;
   }
 
+  /**
+   * @return PHUIButtonView
+   */
   private function newUseResultsDropdown(
     PhabricatorSavedQuery $query,
     array $dropdown_items) {
···
     return $message;
   }
 
+  /**
+   * @return PHUIInfoView
+   */
   private function newOverheatedView(array $results) {
     $message = self::newOverheatedError((bool)$results);
 
···
         ));
   }
 
+  /**
+   * @return PhabricatorActionView
+   */
   private function newBuiltinUseActions() {
     $actions = array();
     $request = $this->getRequest();

src/applications/search/editor/PhabricatorProfileMenuEditEngine.php

···
     return $this;
   }
 
+  /**
+   * @return PhabricatorProfileMenuEngine
+   */
   public function getMenuEngine() {
     return $this->menuEngine;
   }
···
     return $this;
   }
 
+  /**
+   * @return PhabricatorProfileMenuItemConfiguration
+   */
   public function getNewMenuItemConfiguration() {
     return $this->newMenuItemConfiguration;
   }

src/applications/search/engine/PhabricatorApplicationSearchEngine.php

···
     return $this->viewer;
   }
 
+  /**
+   * Set rendering context (e.g. list or panel)
+   *
+   * @param $context string A CONTEXT_* constant
+   */
   public function setContext($context) {
     $this->context = $context;
     return $this;
   }
 
+  /**
+   * Whether this is in the context of rendering a panel
+   *
+   * @return bool True if in panel context
+   */
   public function isPanelContext() {
     return ($this->context == self::CONTEXT_PANEL);
   }

src/applications/search/engine/PhabricatorProfileMenuEngine.php

···
     return $this->viewer;
   }
 
+  /**
+   * @param object $profile_object A PhabricatorApplication subclass
+   */
   public function setProfileObject($profile_object) {
     $this->profileObject = $profile_object;
     return $this;
   }
 
+  /**
+   * @return object A PhabricatorApplication subclass
+   */
   public function getProfileObject() {
     return $this->profileObject;
   }
 
+  /**
+   * @param $custom_phid A User PHID
+   */
   public function setCustomPHID($custom_phid) {
     $this->customPHID = $custom_phid;
     return $this;
   }
 
+  /**
+   * @return string|null A User PHID, or null
+   */
   public function getCustomPHID() {
     return $this->customPHID;
   }
 
+  /**
+   * @return string|null A User PHID, or null
+   */
   private function getEditModeCustomPHID() {
     $mode = $this->getEditMode();
 

src/applications/search/field/PhabricatorSearchField.php

···
     return $this->enableForConduit;
   }
 
+  /**
+   * @return array<ConduitConstantDescription|null>
+   */
   public function newConduitConstants() {
     return array();
   }

src/applications/search/menuitem/PhabricatorProfileMenuItem.php

···
       ->execute();
   }
 
+  /**
+   * @return PhabricatorProfileMenuItemView
+   */
   final protected function newItemView() {
     return new PhabricatorProfileMenuItemView();
   }

src/applications/search/storage/PhabricatorProfileMenuItemConfiguration.php

···
     return ($this->getVisibility() === self::VISIBILITY_DEFAULT);
   }
 
+  /**
+   * @return int|string
+   */
   public function getItemIdentifier() {
     $id = $this->getID();
 
···
     return $this->getBuiltinKey();
   }
 
+  /**
+   * @return string
+   */
   public function getDefaultMenuItemKey() {
     if ($this->getBuiltinKey()) {
       return $this->getBuiltinKey();

src/infrastructure/env/PhabricatorConfigDatabaseSource.php

···
 <?php
 
+/**
+ * Configuration source which reads from the database.
+ */
 final class PhabricatorConfigDatabaseSource
   extends PhabricatorConfigProxySource {