Merge pull request #8242 from Oldiesmann/more_docs

Sources/Actions/Admin/Smileys.php

@@ -2561,7 +2561,8 @@ protected function import(string $smileyPath, bool $create = false): void
  }
 
  /**
- *
+ * @param string $dir The directory to create
+ * @param string $name The name of the set
  */
  protected function createDir(string $dir, string $name): void
  {
@@ -2593,15 +2594,20 @@ protected function createDir(string $dir, string $name): void
  }
 
  /**
- *
+ * @param string $name The desired name for the file
+ * @param string $tmp_name The temporary name for the file
+ * @return bool Whether this is a valid image file
  */
  protected function validateImage(string $name, string $tmp_name): bool
  {
  return in_array(pathinfo($name, PATHINFO_EXTENSION), self::$allowed_extenions) && Utils::checkMimeType($tmp_name, Utils::buildRegex(self::$allowed_mime_types, '~'), true);
  }
 
  /**
- *
+ * @param string $name The desired name of the file
+ * @param string $tmp_name The temporary name of the file
+ * @param array $destination_dirs An array of one or more directories to move this image to
+ * @return array An array of information about the files that were moved
  */
  protected function moveImageIntoPlace(string $name, string $tmp_name, array $destination_dirs): array
  {
@@ -2695,7 +2701,7 @@ protected static function getKnownSmileySets(): void
  }
 
  /**
- *
+ * Saves the list of known smiley sets
  */
  protected static function saveSets(): void
  {
@@ -2723,7 +2729,9 @@ protected static function saveSets(): void
  }
 
  /**
- *
+ * Sanitizes the string and trims unnecessary whitespace.
+ * @var string $string The string to sanitize
+ * @return string The sanitized string
  */
  protected static function sanitizeString(string $string): string
  {

Sources/Actions/Announce.php

@@ -84,7 +84,7 @@ public function execute(): void
  }
 
  /**
- *
+ * Handles selecting which groups to send the announcement to
  */
  public function select(): void
  {
@@ -127,7 +127,7 @@ public function select(): void
  }
 
  /**
- *
+ * Sends the announcement email
  */
  public function send(): void
  {

Sources/Actions/Feed.php

@@ -2950,6 +2950,11 @@ public static function cdataParse(string $data, string $ns = '', bool $force = f
  * Internal methods
  ******************/
 
+ /**
+ * Sets the subaction property
+ * 
+ * @param ?string $subaction The subaction. If not set, checks $_GET['sa'] first, then picks the first value in self::$subactions
+ */
  protected function setSubaction(?string $subaction): void
  {
  if (isset($subaction, self::$subactions[$subaction])) {
@@ -2961,6 +2966,11 @@ protected function setSubaction(?string $subaction): void
  }
  }
 
+ /**
+ * Sets the member property. This is the ID of the person viewing it or the person whose profile feed we're viewing
+ *
+ * @param ?int The member ID
+ */
  protected function setMember(?int $member = 0): void
  {
  // Member ID was passed to the constructor.
@@ -2984,13 +2994,19 @@ protected function setMember(?int $member = 0): void
  Utils::$context['xmlnews_uid'] = $this->member;
  }
 
+ /**
+ * Sets the format based on $_GET['type']
+ */
  protected function setFormat(): void
  {
  if (isset($_GET['type'], self::XML_NAMESPACES[$_GET['type']])) {
  $this->format = $_GET['type'];
  }
  }
 
+ /**
+ * Sets the limit for determining how many items to show
+ */
  protected function setlimit(): void
  {
  // Limit was set via Utils::$context.
@@ -3009,6 +3025,9 @@ protected function setlimit(): void
  Utils::$context['xmlnews_limit'] = $this->limit;
  }
 
+ /**
+ * Checks whether feeds are enabled
+ */
  protected function checkEnabled(): void
  {
  // Users can always export their own profile data.

Sources/Actions/Moderation/Logs.php

@@ -180,28 +180,28 @@ class Logs implements ActionInterface
  /**
  * @var array
  *
- *
+ * An array of search parameters
  */
  protected array $search_params;
 
  /**
  * @var string
  *
- *
+ * The search parameters string
  */
  protected string $search_params_string;
 
  /**
  * @var string
  *
- *
+ * The column being searched
  */
  protected string $search_params_column;
 
  /**
  * @var string
  *
- *
+ * URL-encoded search params
  */
  protected string $encoded_search_params;
 
@@ -229,7 +229,8 @@ public function execute(): void
  }
 
  /**
- *
+ * Handles the admin log.
+ * @uses createList()
  */
  public function adminlog(): void
  {
@@ -243,7 +244,8 @@ public function adminlog(): void
  }
 
  /**
- *
+ * Handles the moderation log
+ * @uses createList()
  */
  public function modlog(): void
  {
@@ -664,7 +666,7 @@ protected function __construct()
  }
 
  /**
- *
+ * Sets up the search
  */
  protected function setupSearch(): void
  {
@@ -713,7 +715,7 @@ protected function setupSearch(): void
  }
 
  /**
- *
+ * Handles deleting log entries
  */
  protected function deleteEntries(): void
  {
@@ -725,7 +727,7 @@ protected function deleteEntries(): void
  }
 
  /**
- *
+ * Handles deleting all entries in either the mod or admin logs
  */
  protected function deleteAll(): void
  {
@@ -748,7 +750,7 @@ protected function deleteAll(): void
  }
 
  /**
- *
+ * Deletes a single log entry
  */
  protected function deleteEntry(): void
  {
@@ -773,7 +775,7 @@ protected function deleteEntry(): void
  }
 
  /**
- *
+ * Sets up all the information for the admin or mod log
  */
  protected function createList(): void
  {

Sources/Actions/Moderation/ReportedContent.php

@@ -1308,7 +1308,7 @@ protected function deleteModComment(int $comment_id): void
  }
 
  /**
- *
+ * Sets up information for the quick buttons for each report
  */
  protected function buildQuickButtons(): void
  {

Sources/Actions/Notify.php

@@ -375,7 +375,7 @@ protected function setMode(): void
  }
 
  /**
- *
+ * Handles loading the notification settings page
  */
  protected function ask(): void
  {

Sources/Actions/Post.php

@@ -577,7 +577,7 @@ protected function loadTopic(): void
  }
 
  /**
- *
+ * Sets up various Utils::$context variables for the template when replying to a topic
  */
  protected function initiateReply(): void
  {
@@ -638,7 +638,7 @@ protected function initiateReply(): void
  }
 
  /**
- *
+ * Sets up the form for posting a new topic
  */
  protected function initiateNewTopic(): void
  {
@@ -665,7 +665,7 @@ protected function initiateNewTopic(): void
  }
 
  /**
- *
+ * Sets up the form for creating a new topic with a poll
  */
  protected function initiatePoll(): void
  {
@@ -687,7 +687,7 @@ protected function initiatePoll(): void
  }
 
  /**
- *
+ * Sets up the form for creating a new event
  */
  protected function initiateEvent(): void
  {
@@ -784,7 +784,7 @@ protected function initiateEvent(): void
  }
 
  /**
- *
+ * Checks whether any new replies have been posted while the user was typing and warns them if so
  */
  protected function checkForNewReplies(): void
  {
@@ -831,7 +831,7 @@ protected function checkForNewReplies(): void
  }
 
  /**
- *
+ * Handles setting the response prefix
  */
  protected function setResponsePrefix(): void
  {
@@ -848,7 +848,7 @@ protected function setResponsePrefix(): void
  }
 
  /**
- *
+ * Handles previewing a post
  */
  protected function showPreview(): void
  {
@@ -1066,7 +1066,7 @@ protected function showPreview(): void
  }
 
  /**
- *
+ * Shows the form for editing a post
  */
  protected function showEdit(): void
  {
@@ -1161,7 +1161,7 @@ protected function showEdit(): void
  }
 
  /**
- *
+ * Shows the form for creating a new post
  */
  protected function showNew(): void
  {
@@ -1263,7 +1263,7 @@ function ($m) {
  }
 
  /**
- *
+ * Handles showing attachments and setting up information for the attachments interface
  */
  protected function showAttachments(): void
  {
@@ -1556,7 +1556,7 @@ function ($val) {
  }
 
  /**
- *
+ * Shows the verification control if necessary
  */
  protected function showVerification(): void
  {
@@ -1573,7 +1573,7 @@ protected function showVerification(): void
  }
 
  /**
- *
+ * Checks for any errors
  */
  protected function checkForErrors(): void
  {
@@ -1608,7 +1608,7 @@ protected function checkForErrors(): void
  }
 
  /**
- *
+ * Sets the page title based on what the user is doing
  */
  protected function setPageTitle(): void
  {
@@ -1628,7 +1628,7 @@ protected function setPageTitle(): void
  }
 
  /**
- *
+ * Sets up the linktree info for the template
  */
  protected function setLinktree(): void
  {
@@ -1647,7 +1647,7 @@ protected function setLinktree(): void
  }
 
  /**
- *
+ * Handles loading drafts
  */
  protected function loadDrafts(): void
  {
@@ -1690,7 +1690,7 @@ protected function loadEditor(): void
  }
 
  /**
- *
+ * Gets information about available message icons for the template
  */
  protected function setMessageIcons(): void
  {
@@ -1736,7 +1736,7 @@ protected function setMessageIcons(): void
  }
 
  /**
- *
+ * Sets up information about each of the form fields
  */
  protected function setupPostingFields(): void
  {