{"action":"closed","issue":{"url":"https://api.github.com/repos/dart-lang/linter/issues/24","labels_url":"https://api.github.com/repos/dart-lang/linter/issues/24/labels{/name}","comments_url":"https://api.github.com/repos/dart-lang/linter/issues/24/comments","events_url":"https://api.github.com/repos/dart-lang/linter/issues/24/events","html_url":"https://github.com/dart-lang/linter/issues/24","id":57262082,"number":24,"title":"Lint to prefer providing type annotations on public APIs (Style Guide).","user":{"login":"pq","id":67586,"avatar_url":"https://avatars.githubusercontent.com/u/67586?v=3","gravatar_id":"","url":"https://api.github.com/users/pq","html_url":"https://github.com/pq","followers_url":"https://api.github.com/users/pq/followers","following_url":"https://api.github.com/users/pq/following{/other_user}","gists_url":"https://api.github.com/users/pq/gists{/gist_id}","starred_url":"https://api.github.com/users/pq/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pq/subscriptions","organizations_url":"https://api.github.com/users/pq/orgs","repos_url":"https://api.github.com/users/pq/repos","events_url":"https://api.github.com/users/pq/events{/privacy}","received_events_url":"https://api.github.com/users/pq/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/dart-lang/linter/labels/enhancement","name":"enhancement","color":"84b6eb"},{"url":"https://api.github.com/repos/dart-lang/linter/labels/Lint%20Request","name":"Lint Request","color":"006b75"},{"url":"https://api.github.com/repos/dart-lang/linter/labels/not%20integrated","name":"not integrated","color":"bfe5bf"},{"url":"https://api.github.com/repos/dart-lang/linter/labels/style","name":"style","color":"fbca04"}],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":5,"created_at":"2015-02-11T00:52:00Z","updated_at":"2015-11-05T19:34:15Z","closed_at":"2015-11-05T19:34:14Z","body":"From [effective dart] (https://www.dartlang.org/effective-dart/design/#do-type-annotate-public-apis):\r\n\r\n**DO** type annotate public APIs.\r\n\r\nType annotations are important documentation for how a library should be used.\r\nAnnotating the parameter and return types of public methods and functions helps\r\nusers understand what the API expects and what it provides.\r\n\r\nNote that if a public API accepts a range of values that Dart's type system\r\ncannot express, then it is acceptable to leave that untyped. In that case, the\r\nimplicit `dynamic` is the correct type for the API.\r\n\r\nFor code internal to a library (either private, or things like nested functions)\r\nannotate where you feel it helps, but don't feel that you *must* provide them.\r\n\r\n**BAD:**\r\n```\r\ninstall(id, destination) {\r\n  // ...\r\n}\r\n```\r\n\r\nHere, it's unclear what `id` is. A string? And what is `destination`? A string\r\nor a `File` object? Is this method synchronous or asynchronous?\r\n\r\n\r\n**GOOD:**\r\n\r\n```\r\nFuture<bool> install(PackageId id, String destination) {\r\n  // ...\r\n}\r\n```\r\nWith types, all of this is clarified.\r\n"}}