search

dart-lang / dartdoc

API documentation tool for Dart.
https://pub.dev/packages/dartdoc
BSD 3-Clause "New" or "Revised" License
473 stars 118 forks source link

flutter's cupertino library docs contain many symbols not specifically related to Cupertino widgets #2207

Open devoncarew opened 4 years ago

devoncarew commented 4 years ago

Opening this issue so we don't lose the feedback. From @timsneath:

The hosted package:cupertino docs have many documented symbols not related to Cupertino widgets (Material, foundation, ...): https://api.flutter.dev/flutter/cupertino/cupertino-library.html. Documenting these is all technically correct, but make it difficult to see what's actually introduced into the Flutter namespace by the cupertino library.

@jcollins-g tells me that there are knobs we could introduce, that flutter could then tweak in it's dartdoc config (https://github.com/flutter/flutter/blob/master/dev/tools/dartdoc.dart#L126), that could improve the situation here.

jcollins-g commented 4 years ago

I see two paths to addressing issues like this in dartdoc. One is to use the existing category support in Dartdoc to collect widgets in category pages, so they can be documented in logical groups independent of the existing API. This would also have the effect of visually tagging Cupertino widgets in libraries in which they appear, helping to sort them out from other reexported symbols. Someone would simply have to do this work of tagging inside Flutter; it's tedious, but not hard. It should be possible to make use of the json file backing the Flutter Gallery to help tag -- or even add something to dartdoc so it can tag categories itself by loading the file.

The second is to introduce the option to cloak some or all non-canonical symbols in library pages. If you mouse over the various symbols on the library page you'll see that widgets simply replicated in cupertino refer to their more logical locations. We could make use of that knowledge and have a flag or tag that says "for this library, do not document all (or these specified) non-canonical symbols".

jcollins-g commented 4 years ago

Switching to P1: significant data exists around this being a win, now.

devoncarew commented 3 years ago

cc @kevmoo who asked about this recently

n7trd commented 2 years ago

This issue does not only apply to cupertino but to other libraries as well.
Example: "material" (way over 1000+ symbols), "widgets" and other pub libraries.

The problem is the use of re-export that gives developers a convenient way to basically import everything with one line, with the downside that the doc becomes extremely overwhelming. Also it is not really obvious what is re-exported from where... There is really a need for a broader discussion & patterns how to use re-exports (if at all) for public apis. I created an issue https://github.com/flutter/flutter/issues/100444 a while ago, cause it mostly affects flutter libraries for some reason.

I don't think it's an issue that should be addressed with some tweak in dartdoc.

jcollins-g commented 1 year ago

Moving to P3 based on @n7trd's comment -- this may be an issue that is outside the scope of a dartdoc change.