Reference links within extension methods are unimplemented

[natebosch]

Given a library like:

extension Foo on String {
  /// Print this and [another].
  void doStuff(String another) {
    print(this + another);
  }
}

Running dart doc crashes. It doesn't happen if I remove [another]. When it tries to resolve the reference there is a type error.

dartdoc failed: type 'Extension' is not a subtype of type 'Class'
package:dartdoc/src/markdown_processor.dart 209:66            _getMatchingLinkElement
package:dartdoc/src/markdown_processor.dart 758:12            _linkDocReference
package:dartdoc/src/markdown_processor.dart 1006:22           Documentation._renderMarkdownToHtml._linkResolver
package:markdown/src/inline_parser.dart 720:14                LinkSyntax._resolveReferenceLink
package:markdown/src/inline_parser.dart 742:9                 LinkSyntax._tryAddReferenceLink
package:markdown/src/inline_parser.dart 692:12                LinkSyntax.onMatchEnd
package:markdown/src/inline_parser.dart 1216:16               TagState.close
package:markdown/src/inline_parser.dart 1155:7                TagState.tryMatch
package:markdown/src/inline_parser.dart 106:57                InlineParser.parse.<fn>
dart:_internal                                                ListIterable.any
package:markdown/src/inline_parser.dart 106:12                InlineParser.parse
package:dartdoc/src/markdown_processor.dart 903:53            MarkdownDocument._parseInlineContent
package:dartdoc/src/markdown_processor.dart 908:9             MarkdownDocument._parseInlineContent
package:dartdoc/src/markdown_processor.dart 928:5             MarkdownDocument.renderLinesToHtml
package:dartdoc/src/markdown_processor.dart 1016:21           Documentation._renderMarkdownToHtml
package:dartdoc/src/markdown_processor.dart 986:9             Documentation._renderHtmlForDartdoc
package:dartdoc/src/markdown_processor.dart 977:7             Documentation.asOneLiner
package:dartdoc/src/model.dart 3901:25                        ModelElement.computeOneLineDoc
package:dartdoc/src/model.dart 3907:21                        ModelElement.oneLineDoc
dart:mirrors                                                  _InstanceMirror.getField
package:mustache/src/renderer.dart 245:29                     Renderer._getNamedProperty
package:mustache/src/renderer.dart 212:16                     Renderer.resolveValue
package:mustache/src/renderer.dart 90:17                      Renderer.visitVariable
package:mustache/src/node.dart 45:43                          VariableNode.accept
package:mustache/src/renderer.dart 64:53                      Renderer.render.<fn>
dart:_internal                                                ListIterable.forEach
package:mustache/src/renderer.dart 64:36                      Renderer.render
package:mustache/src/renderer.dart 195:16                     Renderer.visitPartial
package:mustache/src/node.dart 81:43                          PartialNode.accept
package:mustache/src/node.dart 66:37                          SectionNode.visitChildren.<fn>
dart:core                                                     List.forEach
package:mustache/src/node.dart 66:14                          SectionNode.visitChildren
package:mustache/src/renderer.dart 184:10                     Renderer._renderWithValue
package:mustache/src/renderer.dart 126:28                     Renderer._renderSection.<fn>
dart:core                                                     Iterable.forEach
package:mustache/src/renderer.dart 126:13                     Renderer._renderSection
package:mustache/src/renderer.dart 115:7                      Renderer.visitSection
package:mustache/src/node.dart 63:43                          SectionNode.accept
package:mustache/src/node.dart 66:37                          SectionNode.visitChildren.<fn>
dart:core                                                     List.forEach
package:mustache/src/node.dart 66:14                          SectionNode.visitChildren
package:mustache/src/renderer.dart 184:10                     Renderer._renderWithValue
package:mustache/src/renderer.dart 130:7                      Renderer._renderSection
package:mustache/src/renderer.dart 115:7                      Renderer.visitSection
package:mustache/src/node.dart 63:43                          SectionNode.accept
package:mustache/src/node.dart 66:37                          SectionNode.visitChildren.<fn>
dart:core                                                     List.forEach
package:mustache/src/node.dart 66:14                          SectionNode.visitChildren
package:mustache/src/renderer.dart 184:10                     Renderer._renderWithValue
package:mustache/src/renderer.dart 144:7                      Renderer._renderSection
package:mustache/src/renderer.dart 115:7                      Renderer.visitSection
package:mustache/src/node.dart 63:43                          SectionNode.accept
package:mustache/src/renderer.dart 58:30                      Renderer.render.<fn>
dart:core                                                     List.forEach
package:mustache/src/renderer.dart 58:13                      Renderer.render
package:mustache/src/template.dart 40:14                      Template.render
package:mustache/src/template.dart 33:5                       Template.renderString
package:dartdoc/src/html/html_generator_instance.dart 414:31  HtmlGeneratorInstance._build
package:dartdoc/src/html/html_generator_instance.dart 312:5   HtmlGeneratorInstance.generateExtension
package:dartdoc/src/html/html_generator_instance.dart 175:11  HtmlGeneratorInstance._generateDocs
package:dartdoc/src/html/html_generator_instance.dart 37:7    HtmlGeneratorInstance.generate
dart:async                                                    _AsyncAwaitCompleter.start
package:dartdoc/src/html/html_generator_instance.dart 35:18   HtmlGeneratorInstance.generate
package:dartdoc/src/html/html_generator.dart 117:23           HtmlGenerator.generate
dart:async                                                    _AsyncAwaitCompleter.start
package:dartdoc/src/html/html_generator.dart 83:18            HtmlGenerator.generate
package:dartdoc/dartdoc.dart 107:25                           Dartdoc.generateDocsBase
dart:async                                                    _completeOnAsyncReturn
package:dartdoc/src/model.dart                                PackageBuilder.buildPackageGraph

[jcollins-g]

There seem to be some missing cases around resolution of links to extension methods. Will try to add these in.

[jcollins-g]

It looks like most cases where we are referring to an extension method or its parameters via a documentation reference are not implemented, and risk crashes. Elevating bug to P0.

[mkustermann]

@jcollins-g This might be a blocker for D26, since all our tools need to support extension methods and the core libraries, dart:ffi in particular, are using extension methods now (for which dartdoc fails)

[lrhn]

It does not appear to be just references to extension members, but any reference in the documentation of such.
Both:

extension Foo on int {
  /// Returns [toRadixString] or something.
  String toHexString() => toRadixString(16);
}

and

extension Foo on int {
  /// Returns [int.toRadixString] or something.
  String toHexString() => toRadixString(16);
}

crash. Neither refer to an extension member, but it will have to resolve an identifier relatively to the context of the extension.

[jcollins-g]

yes, everything involving references in extension methods is just broken. today I'll have a PR to patch it over with not implemented yet.

[jcollins-g]

#2040 patches this over, but we still need the actual implementation.

[jcollins-g]

There is a design for the rewrite of comment reference lookups and the beginning of an implementation, but, being a large piece, this keeps getting punted behind other new feature work.

[Hixie]

Any chance we can have a temporary bandaid here that just silences the warning? I'm about to want to commit an extension method to the Flutter codebase and this bug makes it impossible to do so (since we also require documentation on everything). (Ironically we generally disallow extension methods so this would normally not matter but in this case it's specifically a deprecation migration aid...)

[jcollins-g]

Any chance we can have a temporary bandaid here that just silences the warning? I'm about to want to commit an extension method to the Flutter codebase and this bug makes it impossible to do so (since we also require documentation on everything). (Ironically we generally disallow extension methods so this would normally not matter but in this case it's specifically a deprecation migration aid...)

To silence the warning, you can disable the "not-implemented" warning in dartdoc. It is only used for this problem right now.

[Hixie]

Ah awesome, thanks.

[Hixie]

That didn't work because the hyperlinks themselves are still not resolved. :-) Anyway I'll just remove the hyperlinks for now.

[jcollins-g]

This is now fixed in dartdoc 1.0.0.