`void` and `dynamic` Comment References

[RohitSaily]

Related to #60944.

void and dynamic are keywords but only dynamic is recognized in doc comment references. It would be intuitive if they were both recognized in doc comment references since they are used as type identifiers

[lrhn]

Likely reasons is that void is a keyword and dynamic is an identifier exported by dart:core.

That means that dynamic has a place to link to. where void has no place to link to at all.

Well, not really, because there is no dynamic declaration for it anywhere, its name is magically exported by dart:core.
Even if you can have [dynamic] in your docs, what does it do? It doesn't actually link to anything, so it would be better to disallow linking to either.

[FMorschel]

Somewhat related to #60794.

For visibility @bwilkerson @srawlins

[bwilkerson]

void and dynamic are keywords but only dynamic is recognized in doc comment references.

What do you mean by "recognized"?

@jonasfj

[FMorschel]

I think, @bwilkerson, that this is the meaning:

Repro:

/// This is a doc with [void] and [dynamic].
void f() {}

[srawlins]

I've always wanted a way to link to docs for dynamic. See dart-lang/dartdoc#2391

A solution could definitely work for both the analyzer and dartdoc.

[RohitSaily]

Even if you can have [dynamic] in your docs, what does it do? It doesn't actually link to anything, so it would be better to disallow linking to either.

That can make sense right now. They are used exactly like identified types everywhere else so I just defaulted to the behaviour of it being recognized as an in-scope identifier. If some form of documentation or information were generated for it in the future like other built-in types it might be useful then, see previous reply of @srawlins

I've always wanted a way to link to docs for dynamic. See dart-lang/dartdoc#2391

A solution could definitely work for both the analyzer and dartdoc.

[bwilkerson]

A solution could definitely work for both the analyzer and dartdoc.

I think that depends on what the solution is. If dartdoc were to link dynamic to a page on dart.dev that wouldn't answer the question of where to navigate to in the IDE. Curious to know what solution you're thinking of.

[RohitSaily]

A solution could definitely work for both the analyzer and dartdoc.

I think that depends on what the solution is. If dartdoc were to link dynamic to a page on dart.dev that wouldn't answer the question of where to navigate to in the IDE. Curious to know what solution you're thinking of.

In dart-lang/dartdoc#2391, the post dart-lang/dartdoc#2391 (comment) talks about having a markdown file for it. I like the idea, especially if it were done in a manner in which we could do it for arbitrary references for creating custom doc pages that can be referenced via the code documentation, allowing a more wiki-like aggregation of information related to the code and what it achieves

Otherwise some sort of placeholder declaration in code would be needed such that documentation for the specific types are specially treated to resolve to the appropriate documentation

[srawlins]

@lrhn What do you think of stand-alone Markdown files that we can use in IDEs or dartdoc? As a possible implementation:

1. We write sdk/lib/core/types.md or sdk/lib/core/void.md and sdk/lib/core/dynamic.md (I think we also need one for FutureOr.)

2. We can copy the text in these files to dart.dev (@parlough has similar tooling for the analyzer diagnostic text hosted at dart.dev).

3. When we have code like:

   /// Link out to [dynamic], [void], [FutureOr]
   void f(dynamic p1, FutureOr p2) {}

   Then dartdoc can link to those files at dart.dev, and the analysis server can maybe link somewhere (maybe the local SDK if those markdown files can be found?), or at least use the text from those docs to offer hover text in the IDE.

I just looked on dart.dev and we don't seem to have a good page documenting these types... The Dart type system page glosses over them. So it would be good to have text that can be pushed to dart.dev. The spec might be a good starting point for writing these docs. Or just a language expert that wants to take on the task :D.