A recent analysis on the Flutter’s API doc satisfaction showed that users find API docs with full sample code (snippet) more satisfying.

This new feature may scan the class files that generate API docs and identify which class doc contains what content, so that we can tell which classes need more attention, without going through the docs manually.

For example, the Card class's dart file creates an API doc that includes: a short code sample, a full sample in an app (snippet), and an image.

We can identify these by looking at the patterns like these in the code.

1. short code sample: {@tool sample -- See TextField class for an example.
2. short code sample AND full app (snippet): {@tool snippet -- See Card class for an example.
3. image: ![image_description_here](image_url_here.png) -- This pattern may be within a sample.

If a surveyor can scan the dart files and identify the patterns, then the surveyor is expected to generate a file that looks like this.

api, sample, snippet, image // these are column names
TextField, 1, 0, 0
Card, 1, 1, 1
...

Note: There is a script that can show whether a doc has sample or snippet.
TMPDIR=/tmp dart dev/bots/analyze-sample-code.dart --temp=samples running from the flutter directory will generate outputs in /tmp/samples. However, this is not in a desirable format, and does not contain image information.

The example below is from a Flutter Create submission, named ‘realx’.

In this example, the Row widget takes two children, where each child widget is a function soundBtn() that returns a GestureDetector widget.

class HomeRoute extends StatelessWidget {
  row(s1, s2, context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [soundBtn(s1, context), soundBtn(s2, context),],
    );
  }

  soundBtn(sound, context) {
    return GestureDetector(
      onTap: () { Navigator.push(context, MaterialPageRoute(builder: (context) => PlayRoute(sound: sound))); },
      child: Column(
        children: [
          Image.asset('assets/icons/$sound.png'),
          Text(sound.toUpperCase(), style: TextStyle(color: Colors.white, fontSize: 16, letterSpacing: 3.0))
        ],
      ),
    );
  }

But in the Flutter Outline as well as in the surveyor's 2-gram output file, this Row widget doesn’t seem to carry any children widget.

Flutter Outline (partially captured):

Surveyor output:

Column -> Image, 1
Column -> Text, 2
GestureDetector -> Column, 1
GestureDetector -> PlayRoute, 1
null -> GestureDetector, 1
null -> Row, 1 
 . . .

This makes it hard to analyze the characteristics of leaf widgets. I’d like the surveyor to take care of this case.

However, if this is a non-trivial change, as a minimal effort, we could consider adding -> unknown to the 2-gram output file, whenever an empty child or children appears.

For instance, if the analyzer says that the Row widget is a leaf, but if it contains children keyword in the code, add Row -> unknown to the 2-gram output. In that way we can at least know that the Row is not a leaf widget.

For example you might want to skip example and test directories.

See: ditman@bac55aa

The widget example uses the index from package:corpus. In order to update (#26) we'll need to either bring package:corpus to NNBD and the latest analyzer or decouple and inline the index code.

See: dart-lang/language#1005 (comment)

Add a new column that tracks custom vs. flutter

So:

MaterialApp, 1
...

becomes:

MaterialApp, 1, flutter
...

Follow-up from a conversation w/ @csells, it would be nice to be able to suppress all stdout.

For example: you may decide after inspecting a pubspec that you don't want to analyze this package. How to bail out early?

To support cases where clients need to customize SDK location, we could add an API like:

var driver = Driver.forArgs([packageFolder], sdkPath: myPath);
...
await driver.analyze();

For example, to count the number of times a specific rule is enabled.

See: dart-lang/linter#1638 (comment)

Issues to tackle for 1.0.0.

• migrate to NNBD and latest analyzer #26
• introduce sdkPath API #29

To see where this is not working look at accident_reporting:

    MaterialApp(
      home: HomePage(),
      onGenerateRoute: (RouteSettings settings) {
        switch (settings.name) {
          case '/home':
            return PageTransition(child: HomePage(),type: PageTransitionType.leftToRight);
            break;
          case '/second':
            return PageTransition(child: PageOne(),type: PageTransitionType.leftToRight);
            break;
          case '/third':
            return PageTransition(
                child: PageTwo(
                  mapData: settings.arguments,
                ),type: PageTransitionType.leftToRight);
            break;

and notice that we do not track PageTransitions and PageOne, etc.

(EDIT: PageTransition is not a Widget...)

https://github.com/dart-lang/pana/blob/master/lib/src/pubspec.dart#L147

A jumping off point for iteration is defined in example/widget_surveyor.dart

More details/instructions in the README.

Feedback welcome!

/cc @jayoung-lee @InMatrix