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, 4 insertions, 4 deletions

diff --git a/src/ng/directive/ngInclude.js b/src/ng/directive/ngInclude.js
index 47bf742f..0258c9c5 100644
--- a/src/ng/directive/ngInclude.js
+++ b/src/ng/directive/ngInclude.js
@@ -12,13 +12,13 @@
  * application document. This is done by calling {@link ng.$sce#methods_getTrustedResourceUrl
  * $sce.getTrustedResourceUrl} on it. To load templates from other domains or protocols
  * you may either {@link ng.$sceDelegateProvider#methods_resourceUrlWhitelist whitelist them} or
- * {@link ng.$sce#methods_trustAsResourceUrl wrap them} as trusted values. Refer to Angular's {@link
+ * [wrap them](ng.$sce#methods_trustAsResourceUrl) as trusted values. Refer to Angular's {@link
  * ng.$sce Strict Contextual Escaping}.
  *
  * In addition, the browser's
- * {@link https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest
- * Same Origin Policy} and {@link http://www.w3.org/TR/cors/ Cross-Origin Resource Sharing
- * (CORS)} policy may further restrict whether the template is successfully loaded.
+ * [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
+ * and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
+ * policy may further restrict whether the template is successfully loaded.
  * For example, `ngInclude` won't work for cross-domain requests on all browsers and for `file://`
  * access on some browsers.
  *