Enable API doc generation for Dart - quickfix

[chalin]

This issue tracks progress in generating Dart API docs using the current angular.io tool chain. This approach has the advantage of being quick to get up and running, but its main disadvantage (at the moment) is that it is generated from the TS sources.

@kwalrath's task list from #1589

• Make sure the issue search uses the right labels ('api' & 'dart')
• Add known issues to the database.
• Add text to each page linking to known issues.
• Either
  • add Dart examples everywhere or
  • change the text to NOT imply that we have them everywhere.
• Make sure the output is useful (which maybe it will be once Dart examples are everywhere?). I didn't realize that all the generated entries in the docs are directly from TS, not from generated Dart.
• Be more specific in the caveat about how TypeScripty the docs are. Perhaps create a page telling people how to figure out what the API actually is? E.g., how do you find out all the args to bootstrap()? Array -> List, string -> String, boolean -> bool etc.
• Consider pointing people to both the angular.io and dartdocs.org docs? E.g. https://www.dartdocs.org/documentation/angular2/latest/angular2.common/Control-class.html seems to have correct type info except in methods, which lack types (it also shows lots of inherited properties); https://angular.io/docs/dart/latest/api/common/index/Control-class.html is much shorter and/but has little useful information except the text.

[chalin]

Once #1589, is in place, here is what we will be able to do:

• Generate the same API entries that exist on the TS side
• Each API page corresponds to a generated .jade file.

The Jade source files are setup much like the prose, and so we have access to language-specific "macros"; e.g. making the following change in angular/common/src/pipes/async_pipe.ts

- * The `async` pipe subscribes to an `Observable` or `Promise` and returns the latest value it has
+ * The `async` pipe subscribes to !{_an} `!{_Observable}` or `!{_Promise}` and returns the latest value it has

renders as before on the TS side and on the Dart side we get

The async pipe subscribes to a Stream or Future and

With no other change to the API source, we also get @example entries like this:

{@example core/pipes/ts/async_pipe/async_pipe_example.ts region='AsyncPipePromise'}

correctly picking up Dart samples. (This is because such directives become makeExample entries which have been adapted to reinterpret paths based on the page language.)

So the main question to ask users if whether such an incremental improvement over having no API pages at all, would be useful enough.

As a next step I could work on getting proper Dart API signatures.

[chalin]

Superseded by #1880.