Refactor documentation tags and makedoc parsing

[jmooring]

General thoughts:

1. Add support for a @deprecated tag (see Create deprecation process and mechanism #38)
2. Think carefully about whether or not it makes sense to specify types for inputs and output. With Bash, all args are strings, and by definition output is also a string. I still think it makes sense to specify int if the function is expecting a string representation of an integer.
3. Currently I use @returns, but this is misleading. Bash functions don't return anything. Here's what Bash functions can do when invoked through command substitution.

• Set exit status
• Print something to stdout
• Print something to stderr

Maybe the function headers should be more specific. For example:

@param string $foo
  The name of the foo.
@param string $bar (optional)
  The name of the bar.

Note the use of the parenthetical optional descriptor.

@exit_status
  0 upon success, 1 upon failure.

@prints string $quz
  The output of the function.

Most functions print to stdout, but a few print to stderr (die, error, iform, and warn). A couple of options:

1. Add a parenthetical descriptor: @prints string $quz (stderr)
2. Since printing by definition creates a string, replace the type with either stdout or stderr: @prints stdout $quz

I'm leaning towards option 1. Even though printing always produces a string, specifying int is still valuable to indicate that the output is a string representation of an integer. Additionally, option 1 is inline with how we specify optional params.

If the function doesn't print anything, leave this section out.

@global string $baz 
  The name of the baz.

This should probably be directly beneath the params section.

When a function is invoked via command substitution it is executed with a subshell. Within a subshell, a function:

• Can Create a global variable, but it will not be visible to the parent shell.
• Can Read a global variable created in the parent shell.
• Can Update a global variable created in the parent shell, but the parent shell will never see the new value.
• Can Delete (unset) a global variable created in the parent shell, but it will continue to exist in the parent shell.

It would be good to document how a function acts on a particular global variable, meaning, does it Create, Read, Update, or Delete (CRUD)?

Given that most functions are currently (see #41) invoked via command substitution, the most likely or common action would be Read. However, the bfl::declare_ansi_escape_sequences creates a number of global variables.

Perhaps, like @params and @prints, add a parenthetical descriptor to indicate the nature of the interaction:

@global string $baz (create)
@global string $baz (read)
@global string $baz (update)
@global string $baz (delete)

Deprecation. See #38.

@deprecated
  This function has been replaced by foo.

[jmooring]

Also need to update samples, examples, and Coding Standards.