Tweak documentation to make phpDocumentor happier, a=chris

Chris Pollett [2022-08-14 17:Aug:th]
Tweak documentation to make phpDocumentor happier, a=chris
Filename
index.php
src/examples/SearchApi.php
src/library/BPlusTree.php
src/library/IndexDocumentBundle.php
src/library/PackedTableTools.php
src/library/Utility.php
src/library/media_jobs/MediaJob.php
src/library/media_jobs/TrendingHighlightsJob.php
src/library/media_jobs/VideoConvertJob.php
src/locale/el_GR/resources/Tokenizer.php
src/models/BotModel.php
diff --git a/index.php b/index.php
index 63c34ffa5..4812af33a 100644
--- a/index.php
+++ b/index.php
@@ -37,7 +37,7 @@ use seekquarry\yioop\library as L;
  * Used to make using Yioop through this index page rather than as part of
  * a library
  */
-define("seekquarry\\yioop\\BASE_INDEX_ENTRY", true);
+const BASE_INDEX_ENTRY = true;
 /**
  * This will in turn load Config.php
  */
diff --git a/src/examples/SearchApi.php b/src/examples/SearchApi.php
index bf44e1e73..01280eb4c 100644
--- a/src/examples/SearchApi.php
+++ b/src/examples/SearchApi.php
@@ -52,7 +52,7 @@ define("seekquarry\\yioop\\configs\\PARENT_DIR",
     -strlen("/src/examples")));
 define("seekquarry\\yioop\\configs\\BASE_DIR", C\PARENT_DIR . "/src");
 /** Load in global configuration settings; you need this*/
-require_once C\BASE_DIR.'/configs/Config.php';
+require_once C\BASE_DIR . '/configs/Config.php';
 if (!C\PROFILE) {
     echo "Please configure the search engine instance by visiting" .
         "its web interface on localhost.\n";
diff --git a/src/library/BPlusTree.php b/src/library/BPlusTree.php
index 24008c001..62ee11a71 100644
--- a/src/library/BPlusTree.php
+++ b/src/library/BPlusTree.php
@@ -351,7 +351,7 @@ class BPlusTree
      *  column field field this BPlusTree's signature has
      * @param bool $is_encoded_key whether in $row the primary key field has
      *  already been encoded (rawurlencode) or not
-     * @param array& $node an in-memory code of a node (will be modified by
+     * @param array &$node an in-memory code of a node (will be modified by
      *  this method)
      * @param string $archive_filename the name of the archive file associated
      *  with this file used for blob or serial fields.
diff --git a/src/library/IndexDocumentBundle.php b/src/library/IndexDocumentBundle.php
index 875bf8277..e20249913 100644
--- a/src/library/IndexDocumentBundle.php
+++ b/src/library/IndexDocumentBundle.php
@@ -1444,7 +1444,7 @@ class IndexDocumentBundle implements CrawlConstants
      * active partition in an index (the one whose terms haven't yet been added
      * to the B+-tree).
      *
-     * @param array& $postings a reference to an array of posting lists for a
+     * @param array &$postings a reference to an array of posting lists for a
      *  term (this will be changed by this method)
      * @return int sum of the frequencies of term occurrences as given by the
      *  above postings
diff --git a/src/library/PackedTableTools.php b/src/library/PackedTableTools.php
index 7c8757dfd..018dcf023 100644
--- a/src/library/PackedTableTools.php
+++ b/src/library/PackedTableTools.php
@@ -284,7 +284,7 @@ class PackedTableTools
     /**
      * Removes $key and any records associated with it from $table
      *
-     * @param array& $table array of key => records pairs where the
+     * @param array &$table array of key => records pairs where the
      *  key is a string of length given by this PackedTableTool's signature
      *  and the records are packed according this PackedTableTool's signature
      * @param string $key to remove records for
diff --git a/src/library/Utility.php b/src/library/Utility.php
index 3ea2568e6..1b06072ed 100755
--- a/src/library/Utility.php
+++ b/src/library/Utility.php
@@ -287,7 +287,7 @@ function appendUnary($number, $input, &$start_bit_offset,
  * in unary has bit representation n-1 0's followed by a 1.
  *
  * @param string $input the string that we want to decode a unary number from
- * @param int& $start_bit_offset the starting bit offset in $input to start
+ * @param int &$start_bit_offset the starting bit offset in $input to start
  *      decoding from. After the call it will be the position after the decode
  * @return int the decoded unary number
  */
@@ -320,7 +320,7 @@ function decodeUnary($input, &$start_bit_offset)
  *
  * @param int $number to append
  * @param string $input the string to append to.
- * @param int& $start_bit_offset starting location to begin append from
+ * @param int &$start_bit_offset starting location to begin append from
  * @param $num_bits number of bits of $input to append.
  * @return string resulting string
  */
@@ -361,7 +361,7 @@ function appendBits($number, $input, &$start_bit_offset, $num_bits = -1)
  * by number of bits that were able to be decoded.
  *
  * @param string $input string to decode bits from
- * @param int& $start_bit_offset bit offset to start decoding from in $input
+ * @param int &$start_bit_offset bit offset to start decoding from in $input
  * @param int $num_bits number of bits tot try to decode
  * @return int the number decoded
  */
@@ -403,7 +403,7 @@ function decodeBits($input, &$start_bit_offset, $num_bits)
  *
  * @param int $number to append
  * @param string $input the string to append to.
- * @param int& $start_bit_offset starting bit location to begin append from
+ * @param int &$start_bit_offset starting bit location to begin append from
  * @return string resulting string
  */
 function appendGamma($number, $input, &$start_bit_offset)
@@ -422,7 +422,7 @@ function appendGamma($number, $input, &$start_bit_offset)
  * after the decoded integers.
  *
  * @param string $input the string to decode from
- * @param int& $start_bit_offset starting bit location to decode from
+ * @param int &$start_bit_offset starting bit location to decode from
  * @param int $num_decode number of int's to decode
  * @return array decoded int's
  */
@@ -447,7 +447,7 @@ function decodeGammaList($input, &$start_bit_offset, $num_decode)
  * @param array $int_sequence int's to append
  * @param int $modulus i in the 2^i modulus to use for Rice code
  * @param string $output the string to append to.
- * @param int& $start_bit_offset starting bit location to begin append from
+ * @param int &$start_bit_offset starting bit location to begin append from
  * @param int $delta_start if  >= 0 previous int to use for difference list
  *    otherwise the first integer is encoded as itself rather than a difference
  * @return string resulting string
@@ -478,7 +478,7 @@ function appendRiceSequence($int_sequence, $modulus, $output,
  * assumed to be the difference from $delta_start;
  *
  * @param string $input the string to decode from
- * @param int& $start_bit_offset starting bit location to decode from
+ * @param int &$start_bit_offset starting bit location to decode from
  * @param int $num_decode number of int's to decode
  * @param int $delta_start if  >= 0 previous int to use for difference list
  *    otherwise the first integer is decoded as itself rather than a difference
diff --git a/src/library/media_jobs/MediaJob.php b/src/library/media_jobs/MediaJob.php
index f2adff928..ae0828c85 100644
--- a/src/library/media_jobs/MediaJob.php
+++ b/src/library/media_jobs/MediaJob.php
@@ -38,7 +38,7 @@ use seekquarry\yioop\library\FetchUrl;
 use seekquarry\yioop\library\MediaConstants;

 /**
- * Base class for jobs to be carried out by a MediaUpdater process
+ * Base class for jobs to be carried out by a MediaUpdater process.
  * Subclasses of this class correspond to specific jobs for MediaUpdater.
  * Subclasses should implement methods they use among init(),
  * checkPrerequisites(), nondistributedTasks(), prepareTasks(), finishTasks(),
diff --git a/src/library/media_jobs/TrendingHighlightsJob.php b/src/library/media_jobs/TrendingHighlightsJob.php
index bb7f53448..62b6d4233 100644
--- a/src/library/media_jobs/TrendingHighlightsJob.php
+++ b/src/library/media_jobs/TrendingHighlightsJob.php
@@ -43,7 +43,9 @@ use seekquarry\yioop\models\GroupModel;
 use seekquarry\yioop\controllers\CrawlController;

 /**
- * A media job to download
+ * A media job to compute trending terms from the feed search sources, and
+ * to generate a list of top feed items for the landing page for the
+ * different subsearches displlayed on the landing page.
  */
 class TrendingHighlightsJob extends MediaJob
 {
diff --git a/src/library/media_jobs/VideoConvertJob.php b/src/library/media_jobs/VideoConvertJob.php
index e46ef87c6..d91c1db9b 100644
--- a/src/library/media_jobs/VideoConvertJob.php
+++ b/src/library/media_jobs/VideoConvertJob.php
@@ -165,10 +165,10 @@ class VideoConvertJob extends MediaJob
     /**
      * Splits a video into small chunks of 5 minutes
      *
-     * @param string.$file_path full path of video file to be split
+     * @param string $file_path full path of video file to be split
      * @param string file_name.name of video file along with extension
-     * @param.string.$destination_directory.destination directory.name
-     *      where split files would be produced
+     * @param string $destination_directory destination directory name
+     *  where split files would be produced
      */
     public function splitVideo($file_path, $file_name, $destination_directory)
     {
@@ -184,7 +184,7 @@ class VideoConvertJob extends MediaJob
     }
     /**
      * Function to look through all the video directories present in media.
-     * convert folder generated by group model.and split the eligible.files.
+     * convert folder generated by group model and split the eligible files.
      */
     public function splitVideos()
     {
@@ -221,7 +221,7 @@ class VideoConvertJob extends MediaJob
     /**
      * Function to look through all the video directories present in media.
      * convert folder and move them to converted folders if all the split files.
-     * are converted and are present in video.directory.under.converted.
+     * are converted and are present in video directory under converted.
      */
     public function moveVideoFoldersToConvertedDirectory()
     {
@@ -291,7 +291,7 @@ class VideoConvertJob extends MediaJob
     /**
      * Concatenates split video files to generate one video file
      *
-     * @param string.$text_file_name file path containing.the relative file.
+     * @param string $text_file_name file path containing.the relative file.
      *      paths of the files to be concatenated
      * @param string $file_name name of video file to be given to output file.
      * @param string $destination_directory destination directory name
@@ -314,7 +314,7 @@ class VideoConvertJob extends MediaJob
         return false;
     }
     /**
-     * Function to look.through each video directory and call the function to
+     * Function to look through each video directory and call the function to
      * concatenate split files.
      */
     public function concatenateVideos()
@@ -377,8 +377,8 @@ class VideoConvertJob extends MediaJob
      * Handles request to upload the posted data (video file data)
      * in correct location as per the request attributes such as
      * folder name and file name.
-     * @param int $machine_id
-     * @param array $data
+     * @param int $machine_id id of machine doing the put
+     * @param array $data associative array about converted segment
      * @return string message concerning success or non-success of upload
      */
     public function putTasks($machine_id, $data)
diff --git a/src/locale/el_GR/resources/Tokenizer.php b/src/locale/el_GR/resources/Tokenizer.php
index c8112ee9d..1807bbcbf 100644
--- a/src/locale/el_GR/resources/Tokenizer.php
+++ b/src/locale/el_GR/resources/Tokenizer.php
@@ -507,7 +507,7 @@ class Tokenizer
      * first match. If a match is found $word has a corresponding exception
      * stem added back to its end.
      *
-     * @param string& $word term to be stemmed
+     * @param string &$word term to be stemmed
      * @param string $capture_stem_regex a regex of format:
      * /^(stem_pattern)(suffix_pattern)$/ to check against $word. ui is added
      *  to the pattern before used to enable unicode.
diff --git a/src/models/BotModel.php b/src/models/BotModel.php
index 11ac7154a..ea02ce555 100644
--- a/src/models/BotModel.php
+++ b/src/models/BotModel.php
@@ -34,7 +34,7 @@ namespace seekquarry\yioop\models;
  * BotModel is used to handle database statements related to Bot User stories
  * A Bot User Story consists of a sequence of patterns for what a bot should
  * do when another user posts a request to the bot (a message beginning
- * @bot_name) in a discussion group.
+ * with @bot_name) in a discussion group.
  *
  * @author Chris Pollett rewritten from file created by Harika Nukala
  */
ViewGit