Skip to content

dartdoc silently creates bad documentation when run with 2.0.0-dev.22.0 #1603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
jcollins-g opened this issue Feb 8, 2018 · 11 comments
Closed

dartdoc silently creates bad documentation when run with 2.0.0-dev.22.0 #1603

jcollins-g opened this issue Feb 8, 2018 · 11 comments
Assignees
@jcollins-g
Labels
P1 A high priority bug; for example, a single project is unusable or has many test failures

Comments

@jcollins-g
Copy link
Contributor

When trying to unpin dartdoc on travis, I tested it with 2.0.0-dev.22.0 SDK on Linux. This resulted in a big pile of test failures.

screenshot from 2018-02-08 13-41-05

Running with the exact same .packages file works fine in 2.0.0-dev.21.0 -- same analyzer version, same front-end (that's being used by dartdoc), etc.
@jcollins-g jcollins-g added the P1 A high priority bug; for example, a single project is unusable or has many test failures label Feb 8, 2018
@jcollins-g
Copy link
Contributor Author

(This is with a .packages file generated with 2.0.0-dev.22.0 -- 21 works, 22 does not).

@jcollins-g jcollins-g self-assigned this Feb 8, 2018
@jcollins-g
Copy link
Contributor Author

At least some of these test failures appear to be related to core library changes.

@jcollins-g jcollins-g mentioned this issue Feb 8, 2018
Closed
@jcollins-g
Copy link
Contributor Author

One inheritance problem seems to be tests in dartdoc unintentionally depending on ListMixin not adding methods -- but it did in 22.0. Still looking at other issues.

@jcollins-g
Copy link
Contributor Author

Enums seem to be a real issue. Dartdoc will silently drop all enum values.

@jcollins-g
Copy link
Contributor Author

jcollins-g commented Feb 8, 2018 •
edited
Loading

Attempting to figure out where the enum values went by stepping with the debugger landed me with this assertion:

type '_InternalLinkedHashMap<String, DartObjectImpl>' is not a subtype of type 'HashMap<String, DartObjectImpl>' of '_fieldMap@248028204' where
  _InternalLinkedHashMap is from dart:collection
  String is from dart:core
  DartObjectImpl is from package:analyzer/src/dart/constant/value.dart
  HashMap is from dart:collection
  String is from dart:core
  DartObjectImpl is from package:analyzer/src/dart/constant/value.dart

stack trace:

#0      new GenericState (package:analyzer/src/dart/constant/value.dart:1369:21)
#1      ConstFieldElementImpl_EnumValue.evaluationResult (package:analyzer/src/dart/element/element.dart:2070:40)
#2      FieldElementImpl&ConstVariableElement.computeConstantValue (package:analyzer/src/dart/element/element.dart:2684:9)
#3      new ModelElement.from (package:dartdoc/src/model.dart:2656:21)
#4      Class._addSingleField (package:dartdoc/src/model.dart:1108:19)
#5      Class.allFields (package:dartdoc/src/model.dart:1039:7)
#6      Class.instanceProperties (package:dartdoc/src/model.dart:843:23)
#7      Enum.instanceProperties (package:dartdoc/src/model.dart:1330:10)
#8      Class.inheritedMethods (package:dartdoc/src/model.dart:718:5)
#9      Class.allInstanceMethods (package:dartdoc/src/model.dart:486:18)
#10     Class.allModelElements (package:dartdoc/src/model.dart:603:18)
#11     _getResultsForClass (package:dartdoc/src/markdown_processor.dart:677:38)
#12     _findRefElementInLibrary (package:dartdoc/src/markdown_processor.dart:465:9)
#13     _getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:263:9)
#14     _linkDocReference (package:dartdoc/src/markdown_processor.dart:735:12)
#15     Documentation._renderMarkdownToHtml._linkResolver (package:dartdoc/src/markdown_processor.dart:984:26)
#16     LinkSyntax.createNode (package:markdown/src/inline_parser.dart:347:26)
#17     LinkSyntax.onMatchEnd (package:markdown/src/inline_parser.dart:411:16)
#18     TagState.close (package:markdown/src/inline_parser.dart:545:16)
#19     TagState.tryMatch (package:markdown/src/inline_parser.dart:506:7)
#20     InlineParser.parse (package:markdown/src/inline_parser.dart:99:23)
#21     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:881:57)
#22     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:886:9)
#23     MarkdownDocument.renderLinesToHtml (package:dartdoc/src/markdown_processor.dart:906:5)
#24     Documentation._renderMarkdownToHtml (package:dartdoc/src/markdown_processor.dart:994:21)
#25     Documentation._renderHtmlForDartdoc (package:dartdoc/src/markdown_processor.dart:967:9)
#26     Documentation.asHtml (package:dartdoc/src/markdown_processor.dart:943:7)
#27     ModelElement.documentationAsHtml (package:dartdoc/src/model.dart:3015:52)
#28     main.<anonymous closure>.<anonymous closure> (file:///usr/local/google/home/jcollins/dart/dartdoc/test/model_test.dart:971:14)
#29     Declarer._runSetUps.<anonymous closure> (package:test/src/backend/declarer.dart:264:51)
#30     Future.forEach.<anonymous closure> (dart:async/future.dart:484)
#31     Future.doWhile.<anonymous closure> (dart:async/future.dart:526)
#32     StackZoneSpecification._registerUnaryCallback.<anonymous closure>.<anonymous closure> (package:stack_trace/src/stack_zone_specification.dart:129:26)
#33     StackZoneSpecification._run (package:stack_trace/src/stack_zone_specification.dart:209:15)
#34     StackZoneSpecification._registerUnaryCallback.<anonymous closure> (package:stack_trace/src/stack_zone_specification.dart:129:14)
#35     _rootRunUnary (dart:async/zone.dart:1134)
#36     _CustomZone.runUnary (dart:async/zone.dart:1031)
#37     _CustomZone.runUnaryGuarded (dart:async/zone.dart:933)
#38     _CustomZone.bindUnaryCallbackGuarded.<anonymous closure> (dart:async/zone.dart:970)
#39     Future.doWhile (dart:async/future.dart:541)
#40     Future.forEach (dart:async/future.dart:482)
#41     Declarer._runSetUps (package:test/src/backend/declarer.dart:264:18)
<asynchronous suspension>
#42     Declarer.test.<anonymous closure>.<anonymous closure>.<anonymous closure> (package:test/src/backend/declarer.dart:160:23)
<asynchronous suspension>
#43     Invoker.waitForOutstandingCallbacks.<anonymous closure> (package:test/src/backend/invoker.dart:250:15)
<asynchronous suspension>
#44     _rootRun (dart:async/zone.dart:1126)
#45     _CustomZone.run (dart:async/zone.dart:1023)
#46     runZoned (dart:async/zone.dart:1501)
#47     Invoker.waitForOutstandingCallbacks (package:test/src/backend/invoker.dart:247:5)
#48     Declarer.test.<anonymous closure>.<anonymous closure> (package:test/src/backend/declarer.dart:159:33)
#49     _rootRun (dart:async/zone.dart:1126)
#50     _CustomZone.run (dart:async/zone.dart:1023)
#51     runZoned (dart:async/zone.dart:1501)
#52     Declarer.test.<anonymous closure> (package:test/src/backend/declarer.dart:158:13)
<asynchronous suspension>
#53     Invoker._onRun.<anonymous closure>.<anonymous closure>.<anonymous closure>.<anonymous closure> (package:test/src/backend/invoker.dart:404:25)
<asynchronous suspension>
#54     new Future.<anonymous closure> (dart:async/future.dart:174)
#55     StackZoneSpecification._run (package:stack_trace/src/stack_zone_specification.dart:209:15)
#56     StackZoneSpecification._registerCallback.<anonymous closure> (package:stack_trace/src/stack_zone_specification.dart:119:48)
#57     _rootRun (dart:async/zone.dart:1122)
#58     _CustomZone.run (dart:async/zone.dart:1023)
#59     _CustomZone.runGuarded (dart:async/zone.dart:925)
#60     _CustomZone.bindCallbackGuarded.<anonymous closure> (dart:async/zone.dart:965)
#61     StackZoneSpecification._run (package:stack_trace/src/stack_zone_specification.dart:209:15)
#62     StackZoneSpecification._registerCallback.<anonymous closure> (package:stack_trace/src/stack_zone_specification.dart:119:48)
#63     _rootRun (dart:async/zone.dart:1126)
#64     _CustomZone.run (dart:async/zone.dart:1023)
#65     _CustomZone.bindCallback.<anonymous closure> (dart:async/zone.dart:949)
#66     Timer._createTimer.<anonymous closure> (dart:async-patch/dart:async/timer_patch.dart:21)
#67     _Timer._runTimers (dart:isolate-patch/dart:isolate/timer_impl.dart:382)
#68     _Timer._handleMessage (dart:isolate-patch/dart:isolate/timer_impl.dart:416)
#69     _RawReceivePortImpl._handleMessage (dart:isolate-patch/dart:isolate/isolate_patch.dart:165)

@jcollins-g
Copy link
Contributor Author

Some code landed recently according to @scheglov in analyzer to fix this problem, but it hasn't been published yet. It may be possible to work around the flutter bug by doing the thing we should never do: use the dartdoc version in the SDK. Running in checked mode seems to work with the SDK version of dartdoc.

The alternative is to publish a new analyzer and then wait for a new dartdoc before rolling to flutter. (We need to publish analyzer anyway for this, but we could unblock flutter).

@jcollins-g
Copy link
Contributor Author

(There are good reasons not to use the dartdoc in the SDK for flutter, specifically the lack of integration testing for that version of dartdoc, noone uses it so its integration is likely to be a bit rusty -- but it is an option).

@jcollins-g
Copy link
Contributor Author

Now working on verifying I can publish an analyzer package at top of tree, run dartdoc with it, and generate reasonable flutter docs. Tricky, because #1601 means I can't use the AnalysisDriver change just yet.

@jcollins-g
Copy link
Contributor Author

I have verified that the docs generated by the head analyzer with SDK 22.0 are reasonable. CL/PRs coming up for analyzer+kernel+front_end and dartdoc releases.

@jcollins-g
Copy link
Contributor Author

https://dart-review.googlesource.com/c/sdk/+/40401 -- Prepare to publish analyzer

dart-bot pushed a commit to dart-lang/sdk that referenced this issue Feb 9, 2018
@jcollins-g
Prepare to publish analyzer 0.31.1 and associated packages.
75a2661 
Verified that the new analyzer at least smoke-tests on .21 still,
so did not update SDK constraints.  Publish is to address
dart-lang/dartdoc#1603.

Change-Id: I39320e5557344f6c1c79df50b792246fc1c29840
Reviewed-on: https://dart-review.googlesource.com/40401
Commit-Queue: Janice Collins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>
Reviewed-by: Devon Carew <[email protected]>
@jcollins-g
Copy link
Contributor Author

Dartdoc v0.16.0 has been published, which uses the new analyzer and addresses the issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@jcollins-g jcollins-g

Labels
P1 A high priority bug; for example, a single project is unusable or has many test failures
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@jcollins-g