Linking to classes within Dart comments for documentation

Question

Is there a way to link to another class using Dart documentation comments.

In JavaDoc you could use @see com.my.package.Class#method() in your comment and when you click the comment, the IDE takes you to the com.my.package.Class. Is there an equivalent syntax for Dart?

Answer 1

You can use markdown links in DartDoc, so:

/// Floos the ploink.
///
/// The [Ploink] provided as [ploink] is [Ploink.floo]'d.
///
/// Returns the [Floo] resulting from the `floo`'ing of [ploink].
///
/// See also [FlooPloinker] for a class that does the same.
Floo flooThePloink(Ploink ploink) => ploink.floo();

Anything inside [ and ] are links. You can also do external links as [HTTP](https://tools.ietf.org/html/rfc7231), but if there is nothing after the braces, it's considered an internal DartDoc link and is resolved like that identifier would be in the thing being commented on. That includes links to classes like [Object] or methods like [Object.hashCode]. You have to write the "see" yourself, there are no magical @ markers in DartDoc, just prose and links.

You do need to be able to reference the class, so you can't do a dart-doc reference to a class you haven't imported in the library.