Provide documentation for types like Never, void, and dynamic

[srawlins]

A few types are not explicitly declared, like Never, void, and dynamic. However, users may like to have documentation for these types as for any other type. These types may never get standard in-code doc comments; see dart-lang/sdk#43788.

void, for example, is a reserved keyword, as well as a type, so cannot be declared as an actual type. We could try to solve this issue from within dartdoc, instead of the language / dart:core level.

[srawlins]

One solution the team tossed around was individual files in a package which document such things. There could be a specific Markdown file which acts as the doc comment for Never, and another for void, etc. As there should be very very few such files, they could be enumerated in dartdoc_options.yaml (or even de facto searched for if documenting the SDK, which I think already requires a specific flag?).

Within each markdown file, it would indicate within the entity which it documents, and perhaps some other metadata. One possible way to indicate this is Jekyll Front Matter; I think it might be fairly standard. For example, perhaps never.md starts:

---
element: Never
library: dart-core
---

Never is a type that...

When Never is found in a signature, like Never fail(), dartdoc can link the text Never to the docs found in never.md. When [Never] is found as a reference in a documentation comment, dartdoc can link to the docs found in never.md.

In order to document dynamic, void, and Never, this bare functionality might suffice:

• Documentation of such synthetic entities can omit any properties, methods, operators, or constants, any type parameters (until the same mechanism is needed for FutureOr), implementors, super types, ...
• They can assume to be listed no deeper than a library (found in front matter).

[lrhn]

Adding a documentation node without a declaration to hang it on will definitely solve the problem. Well, -ish, because DartDoc would still need to special-case void because it's not exported by dart:core at all. For types which are exported by a dart:* library, adding the name to the "export scope" for documentation purposes too would work.

It's perhaps a big hammer to add a generalized functionality to the DartDoc tool just for three types.
Also, if you try to navigate to the declaration from an IDE, you won't have anywhere to go, so it is just documentation. It'll probably be just as efficient, and way simpler, to just hardcoding the documentation for those three types directly in the analyzer (for hoover-text in IDEs) and the DartDoc output.

[jcollins-g]

Another documentation node that has been proposed is null (lowercase, the value not the type). Special documentation nodes may not be restricted to types. I proposed a heuristic for things that could be covered include "anything we wish to document without a definition that can either be passed as a parameter, returned from a function, or passed as a type parameter".

I don't particularly like hardcoding things into the tool if I can avoid that. Keeping the documentation close to the language implementation by having it be part of the SDK repository (and therefore, in separate files from dartdoc's implementation), would accomplish this. However, if there is a strong need to avoid this obviously hardcoding is possible -- it would need to go in the analyzer though to display in IDEs.

[srawlins]

It'll probably be just as efficient, and way simpler, to just hardcoding the documentation for those three types directly in the analyzer (for hoover-text in IDEs) and the DartDoc output.

I think it is more complicated, not simpler, to maintain the documentation for these types (and perhaps other things like null) in two code repositories (sdk and dartdoc). If a few markdown files exist in the SDK repo, in static locations (sdk/lib/core/never.md perhaps), then dartdoc can hardcode the few static locations, and I believe analyzer could access them easily as well.

I don't particularly like hardcoding things into the tool if I can avoid that. Keeping the documentation close to the language implementation by having it be part of the SDK repository

I agree. I think it is very desirable for the documentation of a thing to be in the same repository, package, or library, as that thing.

[lrhn]

Agree, the documentation should still be in the SDK repo, the dartdoc took should just be hard-coded to find them there when generating docs for dart:core and dart:async (for FutureOr, then we can finally remove the weird class FutureOr declaration).