Add docblocking to functions

1 files changed, 81 insertions, 2 deletions

diff --git a/search.php b/search.php
index b57c1f3..04e12f4 100644
--- a/search.php
+++ b/search.php
@@ -1,5 +1,17 @@
 <?php
 
+/**
+ * Load and parse the config file, setting any defaults here if non-required
+ * fields are not set
+ *
+ * @return string[]
+ * @author Phil Burton <phil@pgburton.com>
+ * @throws Exception when file is not readable
+ * @throws Exception when ini file fails to parse
+ * @throws Exception when url not found in ini file
+ * @throws Exception when command not found in ini file
+ * @throws Exception when pagesize is set incorrectly
+ */
 function getConfig()
 {
     $config = false;
@@ -30,6 +42,14 @@ function getConfig()
     return $config;
 }
 
+/**
+ * Use curl to find get the json file for a url
+ * Using the sha256 hashed password if it's been set in the config
+ *
+ * @param  string[] $config
+ * @return StdClass[]
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function getJsonFromUrl($config)
 {
     $curl = curl_init($config["url"] . "?format=json");
@@ -39,9 +59,25 @@ function getJsonFromUrl($config)
     curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
     $output = json_decode(curl_exec($curl));
     curl_close($curl);
+
+    if (!isset($output)) {
+        throw new Exception(
+            "Could not retrive JSON from http server `"
+            . $config["url"]
+            . "?format=json` using password="
+            . (isset($config["hash"]) ? "true" : "false")
+        );
+    }
     return $output;
 }
 
+/**
+ * Return the help text
+ *
+ * @param  StdClass[] $config
+ * @return string
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function getHelp($config)
 {
     return "Usage: !" . $config["command"] . " [query] #[page] | "
@@ -50,11 +86,28 @@ function getHelp($config)
         . "!" . $config["command"] . " intense marcus #2 (returns the second page of results)";
 }
 
+/**
+ * Get the version string
+ *
+ * @param  stdClass[] $config
+ * @return string
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function getVersion($config)
 {
     return $config["command"] . " v" . "2.0";
 }
 
+/**
+ * Output the given string, adding a new line at the end
+ * If pieces is an array, use the glue to implode and output a single string
+ *
+ * EXIT
+ *
+ * @param  string|string[] $pieces
+ * @param  string $glue
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function output($pieces, $glue = " - ")
 {
     if (!is_array($pieces)) {
@@ -66,6 +119,12 @@ function output($pieces, $glue = " - ")
     exit;
 }
 
+/**
+ * Read stdin and return as a string
+ *
+ * @return string
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function read_stdin()
 {
     $fr = fopen("php://stdin", "r");
@@ -75,6 +134,15 @@ function read_stdin()
     return $input;
 }
 
+/**
+ * Get the start and end index positions for the required page and
+ * page size
+ *
+ * @param  int $page
+ * @param  int $pagesize
+ * @return int[]
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function getPaginationBounds($page, $pagesize)
 {
     return [
@@ -83,6 +151,15 @@ function getPaginationBounds($page, $pagesize)
     ];
 }
 
+/**
+ * Loop through the stdin and parse the arguments given
+ * If we hit a "special" argument then run the specific code and exit
+ * Otherwise we set the page and search terms and return them as an array
+ *
+ * @param  $config
+ * @return mixed[]
+ * @author Phil Burton <phil@pgburton.com>
+ */
 function getFormattedArguments($config)
 {
     $args = explode(" ", read_stdin());
@@ -131,6 +208,9 @@ function getFormattedArguments($config)
     return $formatArgs;
 }
 
+/*********************************
+ * ENTRY POINT FOR FUNCTION HERE *
+ *********************************/
 try {
     $config = getConfig();
     $content = getJsonFromUrl($config);
@@ -185,6 +265,5 @@ try {
     output($out, " - ");
 
 } catch (Exception $e) {
-    echo $e->getMessage() . "\n";
-    die();
+    output($e->getMessage());
 }