👍

To me it isn't a BC break, because the markdown format is not something meant to be analyzed programmatically and only intends to provide a quick documentation of the console application (I'm not even sure it'll be considered as a BC break for json actually, nor any format produced by a command is part of the BC promise).

Status: Reviewed

@ogizanagi I agree that this should't be considered a BC. By the way, a while ago I thought about opening a RFC issue to discuss about removing this feature. Do people really use this Markdown descriptor?

It's nice API doc for a command. Ie. i would use this to generate a README.md for a command repo.

I think it's an easy way to provide a minimalistic documentation for a tool and it is worth keeping it.

I don't see as much utility for the json/xml descriptors though. I don't know what usages it deserves. Someone may try to implement a UI by parsing programmatically those formats, or maybe it can be consumed by generic worker in order to know which command to use and how to call it, but I never seen someone doing nor asking for this.

Guys, before discussing removing something, you should assume that it was added for a reason :) The XML format is used by tools like IDEs to get information about available commands to provide a nice UI for instance.

Yes, the XML export is useful for those cases. But what about the Markdown export?

IIRC, the Markdown format has been added quite recently. So, let's dig a bit into the past PRs to see why it was added.

All formats were added in the same PR by@jfsimon:#7454 ^^

This PR only tends to improve what we already have :) (application_2.md goes from 376 to 350 lines btw).

What about removingIs value required if an option accepts no value?

Thank you@ro0NL.

I was late to this PR, but I was just about to propose the following improvements.

This is how an app description looks like:

And here are some comments:

If the commands are hidden, I think they should not be part of the Mardown format but still be listed in the JSON or XML formats. The idea is that end users should not see them but machines should. 👍 for your other suggestions.

I believe hidden commands are already skipped indeed.

The application version is actually included now in the markdown title (ref,ref2), it wasnt before. However the default version (UNKNOWN) is not shown.

I think we're good :)