docs(bike-shed-migration): let markdown deal with extenal links

It is problematic to use {@link} tags with external links because the
markdown parser converts them to links for us before we parse the @links.
This means that the following tag:

```
{@link http://www.google.com Google}
```

get converted to:

```
{@link <a href="http://www.google.com/"></a> Google}
```

Our {@link} parser then converts this to:

```
<a href="<a">&lt;</a>href="http://www.google.com/"></a> Google}
```

which is clearly a mess.  The best solution is not to use {@link} tags
for external links and just use the standard markdown syntax:

```
[Google](http://www.google.com)
```

In the long run, we could look into configuring or modifying `marked` not
to convert these external links or we could provide a "pre-parser"
processor that dealt with such links before `marked` gets its hands on it.

1 files changed, 1 insertions, 2 deletions

diff --git a/src/ng/controller.js b/src/ng/controller.js
index 1a610b9c..edf5deaf 100644
--- a/src/ng/controller.js
+++ b/src/ng/controller.js
@@ -55,8 +55,7 @@ function $ControllerProvider() {
      * `$controller` service is responsible for instantiating controllers.
      *
      * It's just a simple call to {@link auto.$injector $injector}, but extracted into
-     * a service, so that one can override this service with {@link https://gist.github.com/1649788
-     * BC version}.
+     * a service, so that one can override this service with [BC version](https://gist.github.com/1649788).
      */
     return function(expression, locals) {
       var instance, match, constructor, identifier;