From 2f7c57233ad2d578952dbba5c63ae8d50c1b487a Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 7 Feb 2014 20:40:35 +0000 Subject: 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 Google} ``` Our {@link} parser then converts this to: ``` <href="http://www.google.com/"> 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. --- src/ng/anchorScroll.js | 2 +- src/ng/controller.js | 3 +-- src/ng/directive/input.js | 2 +- src/ng/directive/ngIf.js | 2 +- src/ng/directive/ngInclude.js | 8 ++++---- src/ng/directive/ngPluralize.js | 8 ++++---- src/ng/directive/select.js | 2 +- src/ng/http.js | 27 +++++++++++++-------------- src/ng/location.js | 4 ++-- src/ng/sce.js | 4 ++-- src/ngMock/angular-mocks.js | 4 ++-- src/ngResource/resource.js | 8 ++++---- 12 files changed, 36 insertions(+), 38 deletions(-) (limited to 'src') diff --git a/src/ng/anchorScroll.js b/src/ng/anchorScroll.js index 4cb9a275..f45f67f9 100644 --- a/src/ng/anchorScroll.js +++ b/src/ng/anchorScroll.js @@ -11,7 +11,7 @@ * @description * When called, it checks current value of `$location.hash()` and scroll to related element, * according to rules specified in - * {@link http://dev.w3.org/html5/spec/Overview.html#the-indicated-part-of-the-document Html5 spec}. + * [Html5 spec](http://dev.w3.org/html5/spec/Overview.html#the-indicated-part-of-the-document). * * It also watches the `$location.hash()` and scrolls whenever it changes to match any anchor. * This can be disabled by calling `$anchorScrollProvider.disableAutoScrolling()`. 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; diff --git a/src/ng/directive/input.js b/src/ng/directive/input.js index 92c7d2c5..60cf6dfe 100644 --- a/src/ng/directive/input.js +++ b/src/ng/directive/input.js @@ -1209,7 +1209,7 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$ * * For best practices on using `ngModel`, see: * - * - {@link https://github.com/angular/angular.js/wiki/Understanding-Scopes} + * - [https://github.com/angular/angular.js/wiki/Understanding-Scopes] * * For basic examples, how to use `ngModel`, see: * diff --git a/src/ng/directive/ngIf.js b/src/ng/directive/ngIf.js index 9adb7080..2aaaf2dd 100644 --- a/src/ng/directive/ngIf.js +++ b/src/ng/directive/ngIf.js @@ -19,7 +19,7 @@ * Note that when an element is removed using `ngIf` its scope is destroyed and a new scope * is created when the element is restored. The scope created within `ngIf` inherits from * its parent scope using - * {@link https://github.com/angular/angular.js/wiki/The-Nuances-of-Scope-Prototypal-Inheritance prototypal inheritance}. + * [prototypal inheritance](https://github.com/angular/angular.js/wiki/The-Nuances-of-Scope-Prototypal-Inheritance). * An important implication of this is if `ngModel` is used within `ngIf` to bind to * a javascript primitive defined in the parent scope. In this case any modifications made to the * variable within the child scope will override (hide) the value in the parent scope. 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. * diff --git a/src/ng/directive/ngPluralize.js b/src/ng/directive/ngPluralize.js index a322b3b9..ea5f2779 100644 --- a/src/ng/directive/ngPluralize.js +++ b/src/ng/directive/ngPluralize.js @@ -11,13 +11,13 @@ * These rules are bundled with angular.js, but can be overridden * (see {@link guide/i18n Angular i18n} dev guide). You configure ngPluralize directive * by specifying the mappings between - * {@link http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html - * plural categories} and the strings to be displayed. + * [plural categories](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) + * and the strings to be displayed. * * # Plural categories and explicit number rules * There are two - * {@link http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html - * plural categories} in Angular's default en-US locale: "one" and "other". + * [plural categories](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) + * in Angular's default en-US locale: "one" and "other". * * While a plural category may match many numbers (for example, in en-US locale, "other" can match * any number that is not 1), an explicit number rule can only match one number. For example, the diff --git a/src/ng/directive/select.js b/src/ng/directive/select.js index faa9c7a7..cf0e4cae 100644 --- a/src/ng/directive/select.js +++ b/src/ng/directive/select.js @@ -21,7 +21,7 @@ var ngOptionsMinErr = minErr('ngOptions'); * *
* **Note:** `ngModel` compares by reference, not value. This is important when binding to an - * array of objects. See an example {@link http://jsfiddle.net/qWzTb/ in this jsfiddle}. + * array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/). *
* * Optionally, a single hard-coded `