Issue #7764 has been updated by James Turnbull. Status changed from Merged - Pending Release to Closed
---------------------------------------- Bug #7764: Many small issues with Faces CLI short help https://projects.puppetlabs.com/issues/7764 Author: Randall Hansen Status: Closed Priority: Normal Assignee: Category: Target version: 2.7.0 Affected Puppet version: Keywords: Branch: puppet help * We should be consistent about using "subcommand" versus "face". I've been thinking that we should use "subcommand" anywhere visible from the CLI, and "face" only for the internal API. What do you think? * Render format: what are the options? How do I find out? * Does copyright need to take three lines? Can we put it all on one? * The first sentence of the description is sometimes the summary, sometimes similar to the summary, and sometimes different. We should make the call about this and be consistent. My current best idea is to not show the summary. * Some commands return "Examples" sections. I don't think we should do this, but regardless we should be consistent. * can we make the "--mode" option description live on 1 line? That would make every help command look better. * same for "--terminus" * Some commands we have a "RETURNS" section. This should be consistent for every command that returns data. * E.g., `puppet help certificate_revocation_list info` says "Prints" when it should have a RETURNS section. * In fact, I kind of like it when it's blank (e.g., puppet help certificate_revocation_list destroy) * Some commands have options in USAGE that run together, e.g., USAGE: puppet certificate sign [--terminus TERMINUS][--ca-location LOCATION] * we should put a space between ][ * We should write a test that runs all help commands and looks for broken things, like "invalid for this face" * Some commands (perhaps all?) show the following for `... help save`: "Create or overwrite an object. Save actions cannot currently be invoked from the command line, and are for API use only." * I don't understand this. Does it mean you can't used this "save" action at all? If that's the case, we shouldn't expose it in the CLI help. puppet help catalog * Catalog:apply -- this help doesn't help me :) It's a more verbose way ot saying it, but it doesn't define "catalog" or "apply". * Catalog has two "destroy" actions (and non-helpful help for them). * Catalog has two "search" actions (and non-helpful help for them). puppet help catalog destroy * this returns help, but it should return an error puppet help catalog download * doesn't seem to have help * does show what seems to be boilerplate from secret_agent, which seems bad puppet help catalog find * no help, only description. is this enough? * also, "name" in description but "<key>" in usage puppet help catalog info * help text is duplicated ("Prints the default terminus class for this face.") puppet help catalog save * help text is duplicated ("Create or overwrite an object.") puppet help catalog search * doesn't seem to have help puppet help certificate * find Retrieve a certificate # no period at end of sentence. We should address this globally. * save Invalid for this face. # should not appear * search Invalid for this face. # should not appear puppet help certificate destroy * It would be nice to provide more guidance here. Tell them to use "cert" instead? "Deletes a certificate. This action currently only works with a local CA." puppet help certificate list * RETURNS section instead of description puppet help certificate_request * destroy Invalid for this face. puppet help certificate_revocation_list * save Invalid for this face. * search Invalid for this face. puppet help config print * the RETURNS section is broken up, and it's not immediately clear that the second paragraph is part of it puppet help facts * destroy Invalid for this face. * search Query format unknown; potentially invalid for this face. puppet help facts find * What does this imply? RETURNS: A Puppet::Node::Facts object. puppet help file * destroy Invalid for this face. * search Invalid for this face. puppet help file download * I don't understand the USAGE: USAGE: puppet file download [--terminus TERMINUS] ( {md5}<checksum> | puppet:///... ) puppet help file key * "key" seems like a weird name for this subcommand * "Delete an object." is too brief. What object? puppet help file key * "Retrieve an object by name." is better, but still brief. What object? puppet help file search * "Search for an object or retrieve multiple objects." is too generic. This is a common problem. puppet help man & puppet help man man * these should be the same. I don't imagine that's easy to do :) puppet help node * destroy Invalid for this face. * save Invalid for this face. * search Invalid for this face. puppet help plugin download * "RETURNS: A display-formatted list of the files downloaded. If all plugin files were in sync, this list will be empty." * Is it an empty list, or no return at all? puppet help report * destroy Invalid for this face. * find Invalid for this face. * search Invalid for this face. puppet help report submit * This action is essentially a shortcut and wrapper for the `save` action with the `rest` terminus, which provides additional details in the event of a report submission failure. It is not intended for use from a command line. * If something's not usable from the CLI, we shouldn't be exposing it in CLI help. puppet help resource * destroy Invalid for this face. puppet help resource find * RETURNS: A resource object. * We should be consistent about this. Some places we give the full Ruby object name, some places we give the more generic name. In either case we should provide more context about what "object" means. puppet help resource search * RETURNS: An array of resource objects. * how is it formatted? should we provide formatting advice? puppet help resource_type * destroy Invalid for this face. * save Invalid for this face. puppet help resource_type find * this is huge help. Are all the details necessary? puppet help resource_type search * RETURNS: An array of resource collection info hashes. (See "RETURNS" under `find`.) * s/`find`/`puppet help resource_type find`/ -- You have received this notification because you have either subscribed to it, or are involved in it. To change your notification preferences, please click here: http://projects.puppetlabs.com/my/account -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-bugs?hl=en.
