search

c-blake / cligen

Nim library to infer/generate command-line-interfaces / option / argument parsing; Docs at
https://c-blake.github.io/cligen/
ISC License
509 stars 24 forks source link

[suggestion] Use doc comments or generics to generate help? #111

Closed awr1 closed 5 years ago

awr1 commented 5 years ago

Nim's macro system represents doc comments as AST nodes, and it seems you already use it for the title of the usage docs. Couldn't it be possible to extract doc comments to be used in the help generator for the arguments in lieu of the table system you currently have?

Alternatively, you could maybe invent a generic type to be used for argument usage, e.g.

dispatch:
  proc foo(x         = usage(1,           "Does a very important thing!");
           y         = usage(2'f,         "Does something less important.");
           dangerous = usage(false,       "Be careful!");
           other     = usage[seq[string]]("Put something here")): int =
    ...
c-blake commented 5 years ago

Well, this has come up before. https://github.com/c-blake/cligen/issues/30#issuecomment-410036460 was one reply to that. I ultimately did find an easy way to init from object fields (and those fields used to have doc comments come through in the AST but that feature got removed, I believe).

I doubt existing practice of doc comments used for arguments is very conducive to just wrapping an API that knows nothing about the CLI. There may be something we could do for better defaults with very strong assumptions about formatting of argument doc comments. If you want to try working on that, I am happy to accept PRs along those lines.

A big part of the core idea of cligen is dual maintenance of APIs-CLIs. That also argues against your special argument type alternative since then any API author/maintainer would have to know about all that cligen helper stuff.

c-blake commented 5 years ago

Also, when I try changing test/PerParam.nim to:

proc demo(al_pha=1, ##myalpha
  be_ta=2.0, ##mybeta
  verb=false, ##myverb
  item="", ##myitem
  args: seq[string]) =

and then I instrument cligen.nim to just echo impl.treeRepr, I do not see any of those doc comments show up as nodes. So, I don't see a way to extract the data we would need for better defaults and the alternatives are onerous on API maintainers. So, I don't really see a way out here.