generated docs for flutter plugins also include the dart: docs

[devoncarew]

See https://www.dartdocs.org/documentation/url_launcher/0.4.1/ for an example.

[jcollins-g]

This is a dartdocs.org bug, but exactly what sort of dartdocs.org bug is not clear to me.

My guess is this probably has something to do with flutter shipping their own SDK and dartdocs.org not excluding the flutter SDK explicitly on the commandline (or incorrectly including it).

[jcollins-g]

The inclusion of dart:ui in the generated docs would seem to confirm this hypothesis.

[jcollins-g]

https://www.dartdocs.org/documentation/url_launcher/0.4.1/log.txt

The log suggests dartdoc is not recognizing that the flutter SDK isn't part of the package. But why isn't quite as clear.

[mit-mit]

@jcollins-g in case you need a local repro, these steps work for me:

git clone https://github.com/flutter/plugins.git
cd plugins/packages/url_launcher/
export FLUTTER_ROOT=<path to where you have flutter>/flutter
dartdoc

[mit-mit]

Any news @jcollins-g?

[jcollins-g]

I can reproduce it and am working on a set of command line flags for you to use to work around while I come up with a more permanent fix.

[jcollins-g]

@mit-mit work around with the following command line flag:

--exclude dart.collection,dart.math,dart.core,dart.developer,dart.io,dart.ui,dart.isolate,dart.convert,dart.async,dart.typed_data

This will be safe to use with and without the real fix to this problem.

[jcollins-g]

demoting to P2 since there is a workaround, but will still try to get this fixed soon.

[jcollins-g]

This is no longer needed at head; SDK calculation is now smart enough not to try to include the SDK components in flutter plugins.

[devxpy]

@jcollins-g Does this fix $ dartdoc trying to parse a whole bunch of files, unrelated to my flutter app?

output.txt

[devxpy]

@jcollins-g That workaround doesn't work for me. It's still parsing a whole bunch of files, that are outside the lib/ directory of my project!

[jcollins-g]

Hi @devxpy,

dartdoc parses all files in all packages reachable via the import-export tree of your project (this issue was that sometimes we thought we needed to document some of them when that was inappropriate) and this is expected behavior. It needs to do this because of the way dartdoc's macros and comment reference scoping works, though it probably could be optimized to only do this on demand.

If it is generating docs for things it should not be though, either this or another bug would be appropriate to open.

[devxpy]

though it probably could be optimized to only do this on demand.

The current mechanism doesn't cache things?
Because it currently parses everything again, which takes an absurdly long amount of time, for a relatively small application.

[jcollins-g]

@devxpy

Sadly, no, it does not cache and indeed therefore does take an absurdly long amount of time. I have had some ideas on how to improve that, but performance for dartdoc has not been a high enough priority to be able to allocate the time.

[jcollins-g]

@devxpy To expand very briefly, caching is not straightforward for dartdoc as a change in seemingly unrelated files can impact the documentation generated for another file. This is due to the global scope macros and some comment references can have as well as dartdoc's public interface canonicalization. A design to fix this will either have some heuristics to eliminate those problems in common cases, or we can change some of our scoping rules and then adopt the analysis server's strategy of targeted invalidations when changes are detected. Not a trivial amount of work in either case (though certainly not impossible)

[devxpy]

Thank you for the detailed explanation!

[devxpy]

@jcollins-g Would a file-watcher based "hot-reloading" compiler take a similar amount of effort?

[jcollins-g]

@devxpy Indeed, I would say even more effort. There's a team of folks doing something like that at https://github.com/dart-lang/build, and Flutter of course has hot reloading support.

[srawlins]

Closing as the dart: docs are no longer being included with a flutter plugin's docs.