update documentation

resources/classes/cli_option.php

@@ -40,6 +40,9 @@ class cli_option {
 	private $long_description;
 	private $functions;
 
+	/**
+	 * Constructs an empty cli_option
+	 */
 	public function __construct() {
 		$this->short_option = '';
 		$this->long_option = '';
@@ -49,17 +52,22 @@ class cli_option {
 		$this->functions = [];
 	}
 
+	/**
+	 * A factory method to create a new cli_option
+	 * @param type $options
+	 * @return cli_option
+	 */
 	public static function new(...$options): cli_option {
 		$obj = new cli_option();
 
 		//automatically assign properties to the object that were passed in key/value pairs
 		self::parse_options($obj, $options);
 
-
 		//return the cli_option with all properties filled in that were passed
 		return $obj;
 	}
 
+	// used to parse object values when created
 	private static function parse_options($obj, $options) {
 		foreach ($options as $key => $value) {
 			if (is_array($value)) {
@@ -74,6 +82,11 @@ class cli_option {
 		}
 	}
 
+	/**
+	 * Sets or returns the short option value
+	 * @param string|null $short_option
+	 * @return $this
+	 */
 	public function short_option(?string $short_option = null) {
 		if (!empty($short_option)) {
 			$this->short_option = $short_option;
@@ -82,6 +95,11 @@ class cli_option {
 		return $this->short_option;
 	}
 
+	/**
+	 * Sets or returns the long option value
+	 * @param string|null $long_option
+	 * @return $this
+	 */
 	public function long_option(?string $long_option = null) {
 		if (!empty($long_option)) {
 			$this->long_option = $long_option;
@@ -90,6 +108,11 @@ class cli_option {
 		return $this->long_option;
 	}
 
+	/**
+	 * Set the general description
+	 * @param string|null $description
+	 * @return $this
+	 */
 	public function description(?string $description = null) {
 		if (!empty($description)) {
 			$this->description = $description;
@@ -98,6 +121,11 @@ class cli_option {
 		return $this->description;
 	}
 
+	/**
+	 * Sets or returns the short_description. If short_description is empty then the short_option is used as a default.
+	 * @param string|null $short_description When parameter is null, it returns the currently set value. When not null the short description is set to the passed value.
+	 * @return $this
+	 */
 	public function short_description(?string $short_description = null) {
 		if (!empty($short_description)) {
 			$this->short_description = $short_description;
@@ -116,6 +144,11 @@ class cli_option {
 		return $short_description;
 	}
 
+	/**
+	 * Sets or returns the long_description. If long_description is empty then the long_option is used as a default.
+	 * @param string|null $long_description When parameter is null, it returns the currently set value. When not null the long description is set to the passed value.
+	 * @return $this
+	 */
 	public function long_description(?string $long_description = null) {
 		if ($long_description !== null) {
 			$this->long_description = $long_description;
@@ -134,6 +167,11 @@ class cli_option {
 		return $long_description;
 	}
 
+	/**
+	 * Adds an array of callback functions replacing the existing callback functions
+	 * @param array|null $functions
+	 * @return $this
+	 */
 	public function functions(?array $functions = null) {
 		if ($functions !== null) {
 			$this->functions = $functions;
@@ -142,7 +180,25 @@ class cli_option {
 		return $this->functions;
 	}
 
-	public function function(?string $function = null) {
+	/**
+	 * Appends the callback function to the array of existing callback functions
+	 * @param string|null $function When function param is set, the callback function will be appended to the list of functions. When called without a param, the array will be returned of current callbacks.
+	 * @return $this|array Returns the array of callbacks if no parameters passed or this object when appending a callback
+	 */
+	public function callback(?string $function = null) {
+		if ($function !== null) {
+			$this->functions += [$function];
+			return $this;
+		}
+		return $this->functions;
+	}
+
+	/**
+	 * Appends the callback function to the array of existing callback functions
+	 * @param string|null $function
+	 * @return $this
+	 */
+	public function function_append(?string $function = null) {
 		if ($function !== null) {
 			$this->functions += [$function];
 			return $this;
@@ -150,6 +206,10 @@ class cli_option {
 		return $this->functions;
 	}
 
+	/**
+	 * Returns the array structure required for service
+	 * @return array
+	 */
 	public function to_array(): array {
 		$arr['short_option'] = $this->short_option();
 		$arr['long_option'] = $this->long_option();