Dart docImports allow you to reference identifiers from outside of the current file using square brackets in Dart Doc. The framework contains many of these that reference Material or Cupertino and will need to be migrated before decoupling can be completed.

What should we do about problematic docImports?

docImports are problematic when they reference Material or Cupertino from outside of that referenced library. For example, widgets/scrollbar.dart references both Material and Cupertino so that it can refer to things like [Scrollbar] and [CupertinoScrollbar] in its docs.

Option 0: Do nothing

This is not viable in the long term because it will break dart doc after Material and Cupertino are removed from flutter/flutter. The references in the example above to material.dart and cupertino.dart will not be found.

In the short term immediately after decoupling, because we plan to keep the original Material and Cupertino code in flutter/flutter during a deprecation period, it will not break anything. However, users that click on these links in the framework docs will be taken to the deprecated versions of this code, which is misleading.

Option 1: Remove affected docImports

We could remove the problematic docImports and replace the linked identifiers with unlinked inline code. In the scrollbar.dart example above, we would remove the two docImports and replace [Scrollbar] with `Scrollbar`.

This is an imperfect solution because users of our docs would lose a lot of useful links.

Options 2: Migrate each problematic docImport to reference the new external package

Does dartDoc support referencing something from an external Pub package? How?

Where are problematic docImports located?

Problematic docImports have been seen in the following places, but they may also exist elsewhere:

• packages/flutter_test
• packages/flutter/test
• packages/flutter/lib/src/widgets
• packages/flutter/lib/src/material
• packages/flutter/lib/src/cupertino

How can we prevent this problem in the future?

We should ideally include a lint that can catch problematic docImports, similar to what was done for cross-library test imports in #178693.

Links

This was discovered by @navaronbracke in: https://github.com/flutter/flutter/pull/180456/files#r2700767565