Macros: Will it be possible to Introspect Doc Comments in declaration phase?

[pattobrien]

Moving this conversation here, from a request I had made in the dart analyzer discussion group.

TLDR: are doc comments planned to be supported by the macro introspection APIs?

I've been playing around with the latest macro implementation for the past two weeks or so, to experiment with the new APIs and get a feel for the differences from the analyzer APIs.

I've been building two code-gen related packages with macros in mind (hoping macros could make the UX of the package even better eventually). One of those packages is a cli command/args generator, that can create an ArgParser instance based on the parameters of a function or constructor, like so:

/// Shows the commit logs.
@CommandMacro()
Future<void> log({
  /// Print out the ref names of any commits that are shown.
  Decorate decorate = Decorate.auto,
}) async {
  await Process.run('git', ['log', decorate.name]);
}

enum Decorate { short, full, auto, no }

// -- GENERATED CODE BELOW --

final logArgParser = ArgParser()
  ..addOption(
    'decorate',
    help: 'Print out the ref names of any commits that are shown.', // doc comments are used here
    defaultsTo: 'auto',
    allowed: ['short', 'full', 'auto', 'no'],
    mandatory: false,
    ...
  );

However, I don't see Doc Comments on any of the introspection APIs, - this is despite those elements ~technically~ being static at compile time (I'm sure"static" was never meant to apply to comments, but I think the intent of the question still stands).

FWIW, this is the existing analyzer API that exposes doc comments:

String? getDocComments(Element element) {
  return element.documentationComment;
}

[rrousselGit]

I'd assume this is just an oversight.

Not having access to default values sounds like a major flaw. They are definitely a requirement, as they are often copy-pasted from one place to another.

[jakemac53]

https://github.com/dart-lang/language/issues/3305 is where discussion around default values has been had so far.

Ultimately, I would love to have a language level feature to handle this case. In general, it is not always even possible to duplicate a default value, since it could be private. So, some language feature to just refer to the original default would be better, as it could get around that issue.

[pattobrien]

Ultimately, I would love to have a language level feature to handle this case.

In my particular use case, I think getting access to the Code object of the default is still necessary, to copy the same expression for use outside the scope of the method/function and into the ArgParser.addOption expression - so the default language feature in #2269 wouldn't cut it.

#3305 is where discussion around default values has been had so far.

Thanks! I left a comment in there, and consider the default value portion of this issue as a duplicate. I also changed this issue to hone in on the doc comments portion (unless you'd like a new issue?).