Improve examples

Author: jigarius

examples/input-output.phpakefile

@@ -1,5 +1,7 @@
 <?php
 
+namespace Input_Output;
+
 /**
  * Show today's date.
  *
@@ -20,7 +22,8 @@ function show_date($output) {
  * are used, to describe the parameters. These descriptions are displayed with
  * command-specific help.
  *
- * For example, phpake hello-human --help.
+ * @usage Niki
+ * @usage Niki Martin
  *
  * Notice how the in-built parameter $output was kept towards the end.
  *

examples/namespace.phpakefile

@@ -10,8 +10,6 @@ namespace Fizzbuzz;
  *
  * @param int $n An integer.
  * @return string Fizz, buzz, fizzbuzz, or the number.
- *
- * @see https://en.wikipedia.org/wiki/Fizz_buzz
  */
 function _fizzbuzz(int $n): string {
   $isFizz = ($n % 3 == 0);
@@ -32,6 +30,27 @@ function _fizzbuzz(int $n): string {
   return (string) $n;
 }
 
+/**
+ * Display fizz buzz for a number.
+ *
+ * Here's how you do Fizz Buzz.
+ *
+ * If the number is divisible by 3, "fizz" is displayed.
+ * If the number is divisible by 5, "buzz" is displayed.
+ * If the number is divisible by both, "fizzbuzz" is displayed.
+ * If the number is divisible by neither, the number is displayed.
+ *
+ * See https://en.wikipedia.org/wiki/Fizz_buzz
+ *
+ * @usage 3
+ * @usage 10
+ * @usage 13
+ * @usage 15
+ *
+ * @param string $n A positive integer.
+ * @param $output
+ * @return int|void
+ */
 function number(string $n, $output) {
   if (!is_numeric($n)) {
     $output->writeln('<error>n must be a positive integer.</error>');
@@ -48,6 +67,15 @@ function number(string $n, $output) {
   $output->writeln("<info>$result</info>");
 }
 
+/**
+ * Display fizz buzz for all numbers from 1 to n.
+ *
+ * @usage 20
+ *
+ * @param string $n A positive integer.
+ * @param $output
+ * @return int|void
+ */
 function range(string $n, $output) {
   if (!is_numeric($n) || $n < 0) {
     $output->writeln('<error>n must be a positive integer.</error>');

examples/shell.phpakefile

@@ -1,5 +1,7 @@
 <?php
 
+namespace Shell;
+
 /**
  * List the contents of the working directory.
  *
@@ -17,7 +19,7 @@ function ls() {
  * Phpake sees them as invalid options/switches. To make it clear that those
  * switches are nothing but multiple string arguments, we put -- before them.
  *
- * @usage phpake ssh example.com john.doe -- "-o ForwardAgent=yes"
+ * @usage example.com john.doe -- "-o ForwardAgent=yes"
  *
  * @param string $host A remote host, e.g. example.com
  * @param string|null $user A username. Defaults to the current user.

examples/variadic.phpakefile

@@ -10,6 +10,9 @@
  * To make the $rest argument optional, you can assign a default value of NULL
  * to it. It cannot take any other default values.
  *
+ * @usage India Colombia
+ * @usage India Colombia Canada
+ *
  * @param string $origin Starting location.
  * @param object $output
  * @param array $rest Other destinations.