<div dir="ltr">Documentation can take two forms: reference (e.g. --help) and guide (e.g. man). Here's a "self documented" CLI:<div><br></div><div>foo --help</div><div>foo --baz {--bar [--blatz|--quap]} filespec | --help</div><div>   baz : baz filepec except when quap</div><div>   bar : bar baz filespec as either blatz or quap</div><div>   blatz: blatz contents of filespec as baz bar</div><div>   quap: quap contents of filespec as baz bar</div><div>   help: this highly informative text</div><div><br></div><div><br></div><div>So, tell me exactly what this self-documented CLI does, and how/when/why I'd use it?</div><div><br></div><div>As such, I'd take any request to 'document' any form of API (CLI, REST, etc.)) as a request to also include at least a basic user guide.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Aug 15, 2016 at 8:58 AM, Pete Muir <span dir="ltr"><<a href="mailto:pmuir@redhat.com" target="_blank">pmuir@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">For REST, Swagger seems to be almost universal nowadays.<br>
<div class="HOEnZb"><div class="h5"><br>
On 15 August 2016 at 08:35, Thomas Mäder <<a href="mailto:tmader@redhat.com">tmader@redhat.com</a>> wrote:<br>
> Hi folks,<br>
><br>
> It has been requested that we document our command line interface. To me,<br>
> however it's not quite clear in what form we should do that: technically,<br>
> the cli is self-documenting. If you do "alm-cli --help", it will give you a<br>
> list of possible commands and options. The alm-cli command is mentioned in<br>
> the developer set up section on github. Do we believe this is sufficient?<br>
> What else is necessary?<br>
><br>
> The same question applies to the REST API<br>
><br>
> /Thomas<br>
><br>
> ______________________________<wbr>_________________<br>
> almighty-public mailing list<br>
> <a href="mailto:almighty-public@redhat.com">almighty-public@redhat.com</a><br>
> <a href="https://www.redhat.com/mailman/listinfo/almighty-public" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/almighty-<wbr>public</a><br>
<br>
______________________________<wbr>_________________<br>
almighty-public mailing list<br>
<a href="mailto:almighty-public@redhat.com">almighty-public@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/almighty-public" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/almighty-<wbr>public</a><br>
</div></div></blockquote></div><br></div>