Whitespace / layout cleanup, no functional changes

This fixes a trivial whitespace and layout issue in the spec file, making no
functional changes.  Separated to clarify that.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Use positive assertions, not just "no exceptions", in spec tests

This moves to using a positive assertion that the target responds to a desired
message, rather than an implicit test where the call is made and any exception
is assumed to be "does not respond to".

This ensures the particular test is more robust against future changes, by
focusing on the exact test required.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Fix array validation element declarations without index

In changes made to "clarify" the function arguments in the array element
handling shortcut where an index was omitted, the code was changed to require
a nil value, but a default of an empty hash was supplied.

This broke the shortcut; this change restores it, as well as clarifying the
actual meaning of the content -- nothing, rather than nil, since it is an
object rather than `nil`.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Simplify authz template handling

This simplifies the original "eval" driven templates for authz information,
replacing them with a much simpler and more standard sprintf named
parameter substitution.

This is safer, faster, and generally cleaner than the original; thanks to
@lutter for the tip-off.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Add validation / authz information to command help

This extends the help rendering system by adding the schema data, created from
our validation input, to the output.  Actually rendering the schema down into
markdown is delegated to the schema object itself, since that avoids smearing
knowledge about how the code is implemented through the help subsystem.

This only adds the core infrastructure, and adds support for generating the
access control documentation to the code.  No customization of what is output
is yet available, since no need for it was immediately identified.

https://tickets.puppetlabs.com/browse/RAZOR-196
Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Implement schema attribute documentation

This adds generated documentation to the individual attributes in the
validation system, including author-supplied documentation and information
derived from the validation data.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Correct nested schema authz handling

When authz handling was enabled, I was relatively lazy, and stashed away the
data through the entire hierarchy, but only tested it at the top level.

This worked fine at the time, but caused problems when it came to
documentation because each nested schema was unable to determine if it had
legitimate access control data, or simply the default present in all schema.

This reverses tack: instead of using a default, default to nothing, and
require all commands to declare their access control policy.  This test is
applied at runtime, not "compile" or load time, as other tests are, which does
delay the error report.

On the other hand, it applies this uniformly to all commands, which means that
the only way a command without access control would escape is if we had
literally zero tests for it.

In practice, this showed up eight commands that had only the default access
control patterns -- and in one, and only one, of those cases this was
legitimate.  The remaining seven were genuine shortfalls in the product.

So, it seems like this shift not only improved the ability to document code,
and eliminated "wrong" data from object dumps, but is actually better at
tracking down developer errors than the previous approach was.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>