Currently we do a lot of manual work to maintain shell-api documentation and shell public api input validation when changes are introduced to shell-api.

Documentation is stored away form source and that creates a lot of churn to maintain, on top of that the documentation format is very basic, not easily allowing for custom things like formatting, links, code snippets etc. without changing the documentation json schema.

Validation is manually added for methods with limited runtime API. Even though for every API method we specify type information for the input, there is currently no way to get to this info in runtime.

It would be nice if we could solve both of those issues by automatically extracting shell api metadata from the source code. This might allow us to keep better track of keeping documentation always up to date, provide better output for the help commands, and allow for better, more verbose API calls validation (which means a better understandable help for the end users when their input fails).