Improve ease of discovery of Dart APIs for non-Dart developers

[bkonyi]

I was chatting with @rmacnak-google and he mentioned that it would be nice if we were able to annotate our APIs in such a way that developers familiar with other languages are able to find an equivalent API in Dart when using the search functionality. For example, if a Javascript developer were to search for Promise, the search results would point the user towards our Future documentation.

This seems like it could be useful functionality, particularly within the SDK API documentation, and would make learning Dart easier for those unfamiliar with its APIs.

cc @mit-mit @jcollins-g

[mit-mit]

I agree that explaining Dart concepts in terms of other languages can be very helpful. I'm just not sure it scales to put it into api docs: what set of languages would we include? The top 10? -- that would be a lot of extra content in the api docs...

The current approach we're working is a new set of 'learning dart' docs on dart.dev, each focused on developers originating in a specific language (e.g. 'learning dart as a swift developer). This is an approach that has worked well for Flutter, e.g.: https://flutter.dev/docs/get-started/flutter-for/ios-devs

[bwilkerson]

Thanks for raising the question. I agree that dartdoc probably isn't the best way to solve this issue, so I'm closing this as something we aren't going to do.