documentation does not indicate that packages must analyze correctly for dartdoc to work

[mangini]

UPDATED: the crash happens whenever there is an alias, regardless of library names conflict. Updated snippets below to reflect that. Also tried with dartdoc master instead of 1.0.0, same results.

Running dartdoc in a repro library as below causes an uncaught error.

pubspec.yaml:

name: mysample
environment:
  sdk: '>=2.12.0-0 <3.0.0'

lib/services.dart:

export 'src/test.dart';

lib/src/test.dart:

import 'package:mylib2/src2.dart' as mylib;

class MyTest {
  /// See [mylib.MyClass].
  void foo(String bar) {
  }
}

Running dartdoc (both 1.0.0 and master) on this sample library:

$ dartdoc --output ./docs --format md 
Documenting mysample...
Initialized dartdoc with 40 libraries in 13.1 seconds
Generating docs for library services from package:mysample/services.dart...
  warning: unresolved doc reference [mylib.MyClass]
    from services.MyTest.foo: (file:///tmp/example/mysample/lib/src/test.dart:6:8)

dartdoc 1.0.0 (/tmp/dartdoc-bot.EPegYp/cipd/dart-sdk/bin/snapshots/dartdoc.dart.snapshot) failed: NoSuchMethodError: The getter 'library' was called on null.
Receiver: null
Tried calling: library
#0      Object.noSuchMethod (dart:core-patch/object_patch.dart:63:5)
#1      PackageGraph.findButDoNotCreateLibraryFor (package:dartdoc/src/model/package_graph.dart:907:27)
#2      new ModelElement.fromElement (package:dartdoc/src/model/model_element.dart:129:17)
#3      Prefix.associatedLibrary (package:dartdoc/src/model/prefix.dart:30:43)
#4      Prefix.canonicalModelElement (package:dartdoc/src/model/prefix.dart:37:40)
#5      Prefix.href (package:dartdoc/src/model/prefix.dart:54:7)
#6      PackageGraph.allHrefs (package:dartdoc/src/model/package_graph.dart:603:33)
#7      Dartdoc._validateLinks (package:dartdoc/dartdoc.dart:485:27)
#8      Dartdoc.generateDocsBase (package:dartdoc/dartdoc.dart:217:7)
<asynchronous suspension>
#9      Dartdoc.generateDocs (package:dartdoc/dartdoc.dart:249:28)
<asynchronous suspension>
#10     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/dartdoc.dart:512:9)
<asynchronous suspension>

The issue does only happens if mylib2 is aliased in lib/src/test.dart.

[mangini]

This issue does not happen if I use the flag --no-enhanced-reference-lookup in dartdoc.

[srawlins]

Thanks for the report! Can you confirm whether there is a mylib2 package on disk, with a lib/src2.dart file on disk? Does it contain anything? The pubspec.yaml you include des not reference the mylib2 package...

[mangini]

No, there is no mylib2. If I create one, dartdoc doesn't crash.

I am generating dartdoc for only a subset of Fuchsia libraries (https://fuchsia.dev/reference/dart/) and for efficiency I move only the libraries that I need to a separate directory, create a fake library with the dependencies that I want to document and run dartdoc on it. Until recently (before enhanced reference lookup), this resulted in the intended subset of libraries being documented, and the missing references being ignored with harmless warnings.

[jcollins-g]

dartdoc is not guaranteed to work unless a package analyzes without errors. This means you can not have import lines that import nonexistent libraries. It worked before but really only by accident.

[mangini]

I would counter argue that the requirement "is not guaranteed to work unless a package analyzes without errors" is not mentioned in the dartdoc documentation page: https://dart.dev/tools/dartdoc, and the crash message is not informative. Also, the behavior changed with enhanced-reference-lookup, so it is a regression in behavior and not properly documented.

I request that you reconsider this as a bug. A simple solution can be to document the requirement on the dartdoc page or make the error message more informative, so that developers don't spend hours debugging assuming there's something wrong on their side.

[jcollins-g]

A fair point; reopening as a documentation bug.