pattobrien / cli-gen Goto Github PK

Hi @pattobrien, first excellent job in the package; this looks good!

I might be adding some issues or requests here based on common CLI problems that might fall under the scope of this package.

Problem

Make the auto generation of the CLI version and command more effortless and seamless.

Description

CLIs need to easily check the version. This is used for update checking, compatibility, user support, and so on. Right now, most have to use build_version or a custom script (my case) in order to write the version value from pubspec.

Request

• cli_gen should automatically generate a version.g.dart file based on the pubspec.
• @cliRunner should allow for top level options similar to the @cliCommand, so we can have $ cmd --version which is "somewhat" the standard.

The top level arguments its important on the runner as that is the way also we can configfure global arguments for all commands, or log levels like --verbose and so on.

We already have dedicated models that represent each element of cli_gen (e.g. CliCommandModel) which is essentially a trimmed down version of the Element/AST model, that can be easily used by any code generator.

It would be very useful to have users tap into these builders to define their own static html / js help docs, similar to the FVM docs which were written by hand:

https://fvm.app/documentation/guides/basic-commands

The above docs include the following details for each command (the table shows what is already supported by cli gen today).

Most of the information, besides the examples, would be easy to support.

The biggest question is how to support html/js generation, as rolling our own generator just for cli_gen would not have much benefit as, say, creating a more general-purpose generator for other packages to use. Dartdoc sort of fits this use case, but likely does not support the amount of customization that developers want.

Needs further investigation.

❯ dart bin/main.dart stash apply --help
Commands for managing a stack of stashed changes.

Usage: git stash <subcommand> [arguments]
-h, --help    Print this usage information.

Available subcommands:
  apply               Apply the stash at the given [stashRef] to the working directory.
  my-custom-command   Save your local modifications to a new stash.

Run "git help" to see global options.

A known issue is that a ParameterElement (i.e declarations) of Functions and Methods does not have access to its doc comments via the Element model. Only Constructor parameters are able to access doc comments, but of the Fields or Super parameters that they represent. The lack of support for documenting parameters specifically is likely because Dart recommends against documenting parameters one by one.

There are a couple solutions that we could implement to work around this limitation, none of which are perfect, especially when considering the initial cli-gen + macros prototype.

Option 1 - Get doc comments from Parameter AstNode

This is a 100% usable solution for build_runner cli-gen, but not for macros, since macros do not have access to the Ast model (note: macros API limitations is unconfirmed).

Option 2 - Require annotations for Doc comments

Extremely inelegant solution, this would be a last resort

We'd love some feedback from the community on how doc comments are used in general; how they're utilized in practice may have an effect on which option is selected.