handle dartdoc references to non-imported symbols (was: dartdoc-specific imports)

[Hixie]

Sometimes, a library, like the Flutter rendering library, wants to refer to another library, like the Flutter widgets library, in the documentation, but doesn't want to introduce a dependency in the code. In this case, for example, we definitely do not want any sort of runtime relationship from the rendering library to the widgets library.

We can't use import for this because it risks code accidentally depending through the import.

One possible solution would be to have something like /// @import which would cause the dartdoc code to import it. Another would be for the dartdoc tool to be able to receive a list of imports to imply at the top of every file. I don't really mind how we solve this.

[pq]

cc @keertip for thoughts.

[pq]

Here's an example as food for thought from rendering.dart:

/// The Flutter rendering tree.
/// 
/// To use, import `package:flutter/rendering.dart`.
///
/// The [RenderObject] hierarchy is used by the Flutter Widgets
/// library to implement its layout and painting back-end. Generally,
/// while you may use custom [RenderBox] classes for specific effects
/// in your applications, most of the time your only interaction with
/// the [RenderObject] hierarchy will be in debugging layout issues.
///
/// If you are developing your own library or application directly on
/// top of the rendering library, then you will want to have a binding
/// (see [BindingBase]). You can use [RenderingFlutterBinding], or you
/// can create your own binding. If you create your own binding, it
/// needs to import at least [SchedulerBinding], [GestureBinding],
/// [ServicesBinding], and [RendererBinding]. The rendering library
/// does not automatically create a binding, but relies on one being
/// initialized with those features.

lints to:

[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 13, col 10)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 17, col 11)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 17, col 39)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 19, col 31)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 19, col 51)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 20, col 6)
[lint] Only reference in scope identifiers in doc comments. (packages/flutter/lib/rendering.dart, line 20, col 29)

[devoncarew]

The latest thinking on this is to support something like fully qualified symbol references in square brackets (dartdoc specific imports might get a little hairy). Something like [widgets.Draggable] or [package:flutter/widgets Draggable].

/cc @pq @bwilkerson

[pq]

👍 I'm in favor in taking the cue from Java's qualified names.

Curious where you weigh in @bwilkerson ?

[Hixie]

I could totally work with fully-qualified identifiers in square brackets (assuming they don't render that way, at least).

[pq]

@bwilkerson, @scheglov : how does this proposal sit with you?

[scheglov]

I like the idea of fully qualified names.

[eseidelGoogle]

FWIW this came up again tonight. https://docs.flutter.io/flutter/material/Icons-class.html Icon and IconButton (the classes which consume the data in icons.dart) can't be linked since they're not imported.