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.

https://tickets.puppetlabs.com/browse/RAZOR-197

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.

https://tickets.puppetlabs.com/browse/RAZOR-197

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Add documentation to all validated attributes

This change adds the infrastructure for documenting attributes as part of
their validation setup, as well as adding the documentation itself.

This also adds them to the help output for attributes.

https://tickets.puppetlabs.com/browse/RAZOR-197

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Make attribute documentation mandatory

This alters the attribute documentation from optional to mandatory; a
compile-time error will now be thrown if an undocumented attribute exists.

This ensures that we do not add any further attributes to the system without
documenting them; given that attributes are not accepted without being
validated, this ensures that we can't ship undocumented attributes.

https://tickets.puppetlabs.com/browse/RAZOR-197
Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Make command documentation mandatory

Like attribute documentation, this will now fail if a command is defined
without documentation.  That is a compile / load failure, so will trigger
early in the development cycle; this should be impossible to see in the field.

https://tickets.puppetlabs.com/browse/RAZOR-197
Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Translate help templates

This adds gettext translation to all our help templates.

These are built with ERB, and the static translated string includes the ERB
code, rather than the sprintf style substitution used elsewhere, because that
content controls layout more significantly than most text, so simple
translation may not be appropriate.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>
Update POT file after large i18n burst

This updates the POT file to contain the new strings, since we had a large
burst of them introduced in this change series.  No functional changes.

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