Verify type annotaions on public APIs (#24).

* Implements #24.
* Tweaks the rule boilerplate generator.

BUG=
[email protected]

Review URL: https://codereview.chromium.org//1407283008 .

Author: pq

lib/src/ast.dart

@@ -24,6 +24,7 @@ import 'package:analyzer/src/generated/ast.dart'
         FieldDeclaration,
         FunctionDeclaration,
         FunctionTypeAlias,
+        Identifier,
         MethodDeclaration,
         ReturnStatement,
         SimpleIdentifier,
@@ -243,6 +244,10 @@ AstNode _getNodeToAnnotate(Declaration node) {
   return null;
 }
 
+/// Check if the given identifier has a private name.
+bool isPrivate(SimpleIdentifier identifier) =>
+    identifier != null ? Identifier.isPrivateName(identifier.name) : false;
+
 /// An [Element] processor function type.
 /// If `true` is returned, children of [element] will be visited.
 typedef bool ElementProcessor(Element element);

lib/src/rules.dart

@@ -24,6 +24,7 @@ import 'package:linter/src/rules/prefer_is_not_empty.dart';
 import 'package:linter/src/rules/pub/package_names.dart';
 import 'package:linter/src/rules/slash_for_doc_comments.dart';
 import 'package:linter/src/rules/super_goes_last.dart';
+import 'package:linter/src/rules/type_annotate_public_apis.dart';
 import 'package:linter/src/rules/type_init_formals.dart';
 import 'package:linter/src/rules/unnecessary_brace_in_string_interp.dart';
 import 'package:linter/src/rules/unnecessary_getters_setters.dart';
@@ -46,6 +47,7 @@ final Registry ruleRegistry = new Registry()
   ..register(new SlashForDocComments())
   ..register(new SuperGoesLast())
   ..register(new TypeInitFormals())
+  ..register(new TypeAnnotatePublicApis())
   ..register(new UnnecessaryBraceInStringInterp())
   // Disabled pending fix: https://github.com/dart-lang/linter/issues/35
   //..register(new UnnecessaryGetters())
@@ -68,7 +70,7 @@ class Registry extends Object with IterableMixin<LintRule> {
   ///     my_rule: true
   ///
   /// enables `my_rule`.
-  /// 
+  ///
   /// Unspecified rules are treated as disabled by default.
   Iterable<LintRule> enabled(LintConfig config) => rules
       .where((rule) => config.ruleConfigs.any((rc) => rc.enables(rule.name)));

lib/src/rules/type_annotate_public_apis.dart

@@ -0,0 +1,133 @@
+// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library linter.src.rules.type_annotate_public_apis;
+
+import 'package:analyzer/src/generated/ast.dart';
+import 'package:linter/src/linter.dart';
+import 'package:linter/src/ast.dart';
+
+const desc = r'Type annotate public APIs.';
+
+const details = r'''
+From [effective dart] (https://www.dartlang.org/effective-dart/design/#do-type-annotate-public-apis):
+
+**DO** type annotate public APIs.
+
+Type annotations are important documentation for how a library should be used.
+Annotating the parameter and return types of public methods and functions helps
+users understand what the API expects and what it provides.
+
+Note that if a public API accepts a range of values that Dart's type system
+cannot express, then it is acceptable to leave that untyped. In that case, the
+implicit `dynamic` is the correct type for the API.
+
+For code internal to a library (either private, or things like nested functions)
+annotate where you feel it helps, but don't feel that you *must* provide them.
+
+**BAD:**
+```
+install(id, destination) {
+  // ...
+}
+```
+
+Here, it's unclear what `id` is. A string? And what is `destination`? A string
+or a `File` object? Is this method synchronous or asynchronous?
+
+
+**GOOD:**
+
+```
+Future<bool> install(PackageId id, String destination) {
+  // ...
+}
+```
+
+With types, all of this is clarified.
+''';
+
+class TypeAnnotatePublicApis extends LintRule {
+  TypeAnnotatePublicApis()
+      : super(
+            name: 'type_annotate_public_apis',
+            description: desc,
+            details: details,
+            group: Group.style);
+
+  @override
+  AstVisitor getVisitor() => new Visitor(this);
+}
+
+class Visitor extends SimpleAstVisitor {
+  final LintRule rule;
+  _VisitoHelper v;
+  Visitor(this.rule) {
+    v = new _VisitoHelper(rule);
+  }
+
+  @override
+  visitFieldDeclaration(FieldDeclaration node) {
+    if (node.fields.type == null) {
+      node.fields.accept(v);
+    }
+  }
+
+  @override
+  visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
+    if (node.variables.type == null) {
+      node.variables.accept(v);
+    }
+  }
+
+  @override
+  visitFunctionDeclaration(FunctionDeclaration node) {
+    if (!isPrivate(node.name)) {
+      if (node.returnType == null) {
+        rule.reportLint(node.name);
+      } else {
+        node.functionExpression.parameters.accept(v);
+      }
+    }
+  }
+
+  @override
+  visitMethodDeclaration(MethodDeclaration node) {
+    if (!isPrivate(node.name)) {
+      if (node.returnType == null) {
+        rule.reportLint(node.name);
+      } else {
+        node.parameters.accept(v);
+      }
+    }
+  }
+
+  @override
+  visitFunctionTypeAlias(FunctionTypeAlias node) {
+    if (node.returnType == null) {
+      rule.reportLint(node.name);
+    } else {
+      node.parameters.accept(v);
+    }
+  }
+}
+
+class _VisitoHelper extends RecursiveAstVisitor {
+  final LintRule rule;
+  _VisitoHelper(this.rule);
+
+  @override
+  visitVariableDeclaration(VariableDeclaration node) {
+    if (!isPrivate(node.name)) {
+      rule.reportLint(node.name);
+    }
+  }
+
+  @override
+  visitSimpleFormalParameter(SimpleFormalParameter param) {
+    if (param.type == null) {
+      rule.reportLint(param);
+    }
+  }
+}

test/rules/type_annotate_public_apis.dart

@@ -0,0 +1,46 @@
+// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+const X = ''; //LINT
+
+f() {} //LINT
+
+void g(x) {} //LINT
+
+typedef Foo(x); //LINT
+
+typedef void Bar(int x);
+
+_f() {}
+const _X = '';
+
+class A {
+
+  var x; // LINT
+  final xx = 1; //LINT
+  static const y = ''; //LINT
+  static final z = 3; //LINT
+
+  var zzz, //LINT
+      _zzz;
+
+  f() {} //LINT
+  void g(x) {} //LINT
+  static h() {} //LINT
+  static void j(x) {} //LINT
+  static void k(var v) {} //LINT
+
+  var _x;
+  final _xx = 1;
+  static const _y = '';
+  static final _z = 3;
+
+  void m() {}
+
+  _f() {}
+  void _g(x) {}
+  static _h() {}
+  static _j(x) {}
+  static _k(var x) {}
+}

tool/rule.dart

@@ -83,7 +83,7 @@ ${parser.usage}
 String toClassName(String libName) =>
     libName.split('_').map((bit) => capitalize(bit)).join();
 
-String _generateStub(String libName, String className) => '''
+String _generateStub(String libName, String className) => """
 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
@@ -96,27 +96,40 @@ import 'package:linter/src/linter.dart';
 
 const desc = r' ';
 
-const details = r' ';
+const details = r'''
+
+**DO** ...
+
+**BAD:**
+```
+
+```
+
+**GOOD:**
+```
+
+```
+
+''';
 
 class $className extends LintRule {
   $className() : super(
           name: '$libName',
-          description: desc,
-          details: details,
-          group: Group.STYLE_GUIDE,
-          kind: Kind.AVOID);
+            description: desc,
+            details: details,
+            group: Group.style);
 
   @override
   AstVisitor getVisitor() => new Visitor(this);
 }
 
 class Visitor extends SimpleAstVisitor {
-  LintRule rule;
+  final LintRule rule;
   Visitor(this.rule);
 
 
 }
-''';
+""";
 
 String _generateTest(String libName, String className) => '''
 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file