dartdoc failed: type 'Extension' is not a subtype of type 'Class'

[dcharkes]

dartdoc fails on generating the API docs for dart:ffi after adopting extension methods in dart:ffi. Specifically, /// [block] comments on extension methods are broken.

The pinned version in the dart-sdk is "dartdoc_tag" : "v0.28.7",, which is the latest version.

This blocks the Dart 2.6 release, which should ship dart:ffi with extension methods.

I'll take a look at this myself today to see if I can figure this out.

Full stacktrace:

Generating docs for library dart:ffi from dart:ffi...

stderr:  Documenting Dart...
  warning: ambiguous reexport of dart-_internal.HttpStatus, canonicalization candidates: (dart:html, dart:io) -> dart:io (confidence 0.000)
    from dart-_internal.HttpStatus: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/internal/internal.dart:209:16)
        dart:html: 1.010 - embeds package name (+1.000), name is long (+0.01000)
        dart:io: 1.010 - embeds package name (+1.000), name is long (+0.01000)
            Use {@canonicalFor dart:_internal.HttpStatus} in the desired library's documentation to resolve
            the ambiguity and/or override dartdoc's decision, or structure your package 
            so the reexport is less ambiguous.  The symbol will still be referenced in 
            all candidates -- this only controls the location where it will be written 
            and which library will be displayed in navigation for the relevant pages.
            The flag --ambiguous-reexport-scorer-min-confidence allows you to set the
            threshold at which this warning will appear.
  warning: dart:cli has no library level documentation comments, from dart-cli: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/cli/cli.dart:6:9)
  warning: unresolved doc reference [Uint8List.length], from dart-convert.Base64Codec.decode: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/convert/base64.dart:82:13)
  warning: unresolved doc reference [Uint8List.buffer], from dart-convert.Base64Codec.decode: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/convert/base64.dart:82:13)
  warning: unresolved doc reference [Uint8List.length], from dart-convert.Base64Decoder.convert: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/convert/base64.dart:481:13)
  warning: unresolved doc reference [Uint8List.buffer], from dart-convert.Base64Decoder.convert: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/convert/base64.dart:481:13)
  warning: unresolved doc reference [allocate]
    from dart-ffi.unsized: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/ffi/annotations.dart:37:7)
    in documentation inherited from dart-ffi.unsized: (file:///b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/lib/ffi/annotations.dart:37:7)

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 3895:25                        ModelElement.computeOneLineDoc
package:dartdoc/src/model.dart 3901:21                        ModelElement.oneLineDoc
package:dartdoc/src/model.dart 2169:39                        GetterSetterCombo.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
===== asynchronous gap ===========================
package:dartdoc/src/html/html_generator.dart 117:23           HtmlGenerator.generate
===== asynchronous gap ===========================
package:dartdoc/dartdoc.dart 107:25                           Dartdoc.generateDocsBase
===== asynchronous gap ===========================
package:dartdoc/dartdoc.dart 134:43                           Dartdoc.generateDocs
===== asynchronous gap ===========================
dart:async                                                    runZoned
third_party/pkg/dartdoc/bin/dartdoc.dart 96:13                main.<fn>
===== asynchronous gap ===========================
package:stack_trace                                           Chain.capture
third_party/pkg/dartdoc/bin/dartdoc.dart 95:17                main


Traceback (most recent call last):
  File "/b/s/w/ir/cache/builder/sdk/tools/bots/dart_sdk.py", line 252, in <module>
    CreateUploadAPIDocs()
  File "/b/s/w/ir/cache/builder/sdk/tools/bots/dart_sdk.py", line 112, in CreateUploadAPIDocs
    BuildDartdocAPIDocs(dartdoc_dir)
  File "/b/s/w/ir/cache/builder/sdk/tools/bots/dart_sdk.py", line 48, in BuildDartdocAPIDocs
    '--footer', footer_file, '--rel-canonical-prefix=' + url
  File "/b/s/w/ir/cache/builder/sdk/tools/bots/bot_utils.py", line 233, in run
    raise Exception("Failed to execute %s." % command)
Exception: Failed to execute ['/b/s/w/ir/cache/builder/sdk/out/ReleaseX64/dart-sdk/bin/dart', '/b/s/w/ir/cache/builder/sdk/third_party/pkg/dartdoc/bin/dartdoc.dart', '--sdk-docs', '--output', '/b/s/w/ir/cache/builder/sdk/out/ReleaseX64/gen-dartdocs', '--footer', '/b/s/w/ir/cache/builder/sdk/tools/bots/dartdoc_footer.html', '--rel-canonical-prefix=https://api.dartlang.org/stable'].
!@@@STEP_FAILURE@@@

[dcharkes]

Workaround that makes generating dartdoc succeed:

diff --git a/lib/src/markdown_processor.dart b/lib/src/markdown_processor.dart
index 486334bf..4f6c538f 100644
--- a/lib/src/markdown_processor.dart
+++ b/lib/src/markdown_processor.dart
@@ -184,7 +184,10 @@ class IterableBlockParser extends md.BlockParser {
 ModelElement _getPreferredClass(ModelElement modelElement) {
   if (modelElement is EnclosedElement &&
       (modelElement as EnclosedElement).enclosingElement is Container) {
-    return (modelElement as EnclosedElement).enclosingElement;
+    final enclosingElement = (modelElement as EnclosedElement).enclosingElement;
+    if (enclosingElement is Class) {
+      return enclosingElement;
+    }
   } else if (modelElement is Class) {
     return modelElement;
   }

But this raises the question whether _MarkdownCommentReference should have a preferredExtensionMethod besides a preferredClass, or whether preferredClass should be renamed to work with classes and extension methods. (Edit: maybe it should be the class that it is an extension on. Edit 2: maybe not, because a [T] might refer to a type argument of the extension, rather than the surrounding class.)

/// Represents a single comment reference.
class _MarkdownCommentReference {
  // ..

  /// Disambiguate inheritance with this class.
  final Class preferredClass;

/cc @jcollins-g

[dcharkes]

Duplicate of #2033.