Bug 642335 - Some Markdown links are broken; r=adw

mozilla · Mar 31, 2011 · e2eced3 · e2eced3
1 parent 3aa49d0
commit e2eced3
Show file tree

Hide file tree

Showing 19 changed files with 124 additions and 125 deletions.
diff --git a/packages/addon-kit/docs/tabs.md b/packages/addon-kit/docs/tabs.md
@@ -136,8 +136,8 @@ If present and true, the new tab will be opened to the right of the active tab
 and will not be active. This is an optional property.
 
 @prop [isPinned] {boolean}
-If present and true, then the new tab will be pinned as an app tab.
-[app tab]:http://blog.mozilla.com/faaborg/2010/07/28/app-tabs-in-firefox-4-beta-2/
+If present and true, then the new tab will be pinned as an
+[app tab](http://support.mozilla.com/en-US/kb/what-are-app-tabs).
 
 @prop [onOpen] {function}
 A callback function that will be registered for 'open' event.
@@ -191,9 +191,9 @@ This property can be set to change it's relative position.
 
 <api name="isPinned">
 @property {boolean}
-Whether or not tab is pinned as an [app tab].
+Whether or not tab is pinned as an [app tab][].
 This property is read-only.
-[app tab]:http://blog.mozilla.com/faaborg/2010/07/28/app-tabs-in-firefox-4-beta-2/
+[app tab]:http://support.mozilla.com/en-US/kb/what-are-app-tabs
 </api>
 
 <api name="getThumbnail">
@@ -203,8 +203,8 @@ Returns thumbnail data URI of the page currently loaded in this tab.
 
 <api name="pin">
 @method
-Pins this tab as an [app tab].
-[app tab]:http://blog.mozilla.com/faaborg/2010/07/28/app-tabs-in-firefox-4-beta-2/
+Pins this tab as an [app tab][].
+[app tab]:http://support.mozilla.com/en-US/kb/what-are-app-tabs
 </api>
 
 <api name="unpin">

diff --git a/packages/api-utils/README.md b/packages/api-utils/README.md
@@ -5,7 +5,7 @@ the basis for the Add-on SDK.
 To address issues present in traditional Extension development,
 API Utils provides mechanisms for:
 
-* writing and executing test cases, inspired by Python's [nose]
+* writing and executing test cases, inspired by Python's [nose][]
   package,
 * tracking JS objects of interest to aid in memory profiling and leak
   detection,

diff --git a/packages/api-utils/docs/content.md b/packages/api-utils/docs/content.md
@@ -1,11 +1,11 @@
 <!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] -->
 
-The `content` module exports three different traits [Loader], [Worker] and
-[Symbiont]. None of this traits is intended to be used directly by programs.
+The `content` module exports three different traits [Loader][], [Worker][] and
+[Symbiont][]. None of this traits is intended to be used directly by programs.
 Rather, they are intended to be used by other modules that provide high
 level APIs to programs or libraries.
 
-[Loader]:#module/api-utils/content/loader
-[Worker]:#module/api-utils/content/worker
-[Symbiont]:#module/api-utils/content/symbiont
+[Loader]:packages/api-utils/docs/content/loader.html
+[Worker]:packages/api-utils/docs/content/worker.html
+[Symbiont]:packages/api-utils/docs/content/symbiont.html
 
diff --git a/packages/api-utils/docs/content/loader.md b/packages/api-utils/docs/content/loader.md
@@ -1,14 +1,12 @@
 <!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] -->
 
-Loader
-------
-
 Loader is base trait and it provides set of core properties and associated
 validations. Trait is useful for all the compositions providing high level
 APIs for creating JavaScript contexts that can access web content.
 
-Loader is composed from the [EventEmitter] trait, therefore instances
-of Loader and their descendants expose all the public properties
+Loader is composed from the
+[EventEmitter](packages/api-utils/docs/events.html) trait, therefore
+instances of Loader and their descendants expose all the public properties
 exposed by EventEmitter along with additional public properties:
 
 Value changes on all of the above mentioned properties emit `propertyChange`

diff --git a/packages/api-utils/docs/content/symbiont.md b/packages/api-utils/docs/content/symbiont.md
@@ -34,28 +34,30 @@ Examples
       }
     });
 
-See the [panel] module for a real-world example of usage of this module.
+See the [panel][] module for a real-world example of usage of this module.
 
-[panel]:#module/api-utils/panel
+[panel]:packages/addon-kit/docs/panel.html
 
 Reference
 ---------
 
 <api name="Symbiont">
 @class
-Symbiont is composed from the [Worker] trait, therefore instances
+Symbiont is composed from the [Worker][] trait, therefore instances
 of Symbiont and their descendants expose all the public properties
-exposed by [Worker] along with additional public properties that
+exposed by [Worker][] along with additional public properties that
 are listed below:
 
-[Worker]:#module/api-utils/content/worker
+[Worker]:packages/api-utils/docs/content/worker.html
+
 <api name="Symbiont">
 @constructor
 Creates a content symbiont.
 @param options {object}
-  Options for the constructor. Includes all the keys that [Worker] constructor
-  accepts and few additional:
-[Worker]:#module/api-utils/panel
+  Options for the constructor. Includes all the keys that
+the [Worker](packages/api-utils/docs/content/worker.html)
+constructor accepts and a few more:
+
   @prop [frame] {object}
     The host application frame in which the page is loaded.
     If frame is not provided hidden one will be created.
@@ -100,9 +102,9 @@ The URL of the content loaded.
 
 <api name="allow">
 @property {object}
-Permissions for the content, with the following keys:
-  @prop script {boolean}
-  Whether or not to execute script in the content.  Defaults to true.
+Permissions for the content, with a single boolean key called `script` which
+defaults to true and indicates whether or not to execute scripts in the
+content.
 </api>
 
 </api>

diff --git a/packages/api-utils/docs/content/worker.md b/packages/api-utils/docs/content/worker.md
@@ -1,22 +1,24 @@
 <!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] -->
 
-Introduction
-------------
+This module exports the `Worker` trait, which may be used to construct objects
+implementing the [Worker][] interface defined by the W3C, with minor
+differences.
 
-Module exports `Worker` trait may be used for constructing objects
-implementing [Worker] interface defined by the W3C, with minor differences.
 Content workers are message-passing facilities for communication between
-code running in the content and add-on process. It is important to note that
-unlike "web workers," this workers run in the same process as web content and
-browser chrome, and therefore code within workers can block UI.
+[content scripts](dev-guide/addon-development/web-content.html) and the main
+add-on code.
+
+It is important to note that unlike "web workers," these workers run in the
+same process as web content and browser chrome, so code within workers can
+block the UI.
 
 [Worker]:http://www.w3.org/TR/workers/#worker
 
 <api name="Worker">
 @class
-Worker is composed from the [EventEmitter] trait, therefore instances
+Worker is composed from the [EventEmitter][] trait, therefore instances
 of Worker and their descendants expose all the public properties
-exposed by [EventEmitter] along with additional public properties that
+exposed by [EventEmitter][] along with additional public properties that
 are listed below.
 
 Content workers may emit two types of events:
@@ -44,7 +46,8 @@ that occurs in one of the content scripts.
     });
     worker.postMessage({ name: 'worker'});
 
-[EventEmitter]:#module/api-utils/events
+[EventEmitter]:packages/api-utils/docs/events.html
+
 <api name="Worker">
 @constructor
 Creates a content worker.
@@ -82,7 +85,7 @@ The URL of the content.
 <api name="tab">
 @property {object}
 If this worker is attached to a content document, returns the related 
-[tab](#module/addon-kit/tabs).
+[tab](packages/addon-kit/docs/tabs.html).
 
 </api>
 

diff --git a/packages/api-utils/docs/cortex.md b/packages/api-utils/docs/cortex.md
@@ -1,6 +1,5 @@
-# Cortex #
 
-## property encapsulation ##
+## Property Encapsulation ##
 
 In JavaScript it is not possible to create properties that have limited or
 controlled accessibility. It is possible to create non-enumerable and
@@ -30,7 +29,7 @@ is that there is no immediate solution for inheriting access to the privates
     }
     Derived.prototype = Object.create(Foo.prototype);
 
-## facade objects ##
+## Facade Objects ##
 
 Alternatively constructor can returned facade objects - proxies to the
 instance's public properties:
@@ -66,7 +65,7 @@ both own and inherited private properties, it does not addresses following:
  - Behavior of `instanceof` is broken, since `new Derived() instanceof Derived`
    is going to evaluate to `false`.
 
-## Temper proving with property descriptor maps ##
+## Tamper Proofing with Property Descriptor Maps ##
 
 In ES5 new property descriptor maps were introduced, which can be used as a
 building blocks for defining reusable peace of functionality. To some degree
@@ -104,7 +103,7 @@ they are not exposed by default).
       DerivedDescriptor[key] = FooDescriptor[key];
     });
 
-## cortex objects ##
+## Cortex Objects ##
 
 Last approach solves all of the concerns, but adds complexity, verbosity
 and decreases code readability. Combination of `Cortex`'s and `Trait`'s

diff --git a/packages/api-utils/docs/e10s.md b/packages/api-utils/docs/e10s.md
@@ -1,6 +1,6 @@
 <span class="aside">
-For a high-level overview of out-of-process add-ons, see the [Out-of-Process
-Add-ons][] internals guide.
+For a high-level overview of out-of-process add-ons, see the
+[Out-of-Process Add-ons][] internals guide.
 </span>
 
 The `e10s` module allows add-ons to execute in a separate process from Firefox
@@ -74,8 +74,8 @@ mechanism:
 
 When sending events or calling functions in another process, the chrome and
 add-on processes are allowed to send JSON-serializable arguments. Additionally,
-they can send a special type of object called a *handle*. See the [MDN Handle
-Documentation][] for more information on these.
+they can send a special type of object called a *handle*. See the
+[MDN Handle Documentation][] for more information on these.
 
 Here's a simple example of a handle being used to remember a callback function
 on the add-on side:

diff --git a/packages/api-utils/docs/es5.md b/packages/api-utils/docs/es5.md
@@ -1,45 +1,50 @@
-The `es5` module provides shim layer to a versions of firefox not yet
-implementing EcmaScript 5 features.
+The `es5` module provides shim layer to a versions of Firefox that do not yet
+implement certain EcmaScript 5 features.
 
-- New API's are described in the official [ES5 specification].
-- John Resig made post with good [introduction] of new API's.
-- Google tech talk [changes to JavaScript] is also a good walk through.
+For more information on EcmaScript 5:
+
+* The new APIs are described in the official [ES5 specification][].
+* A good [introduction][] to the new APIs by John Resig.
+* A Google tech talk on [changes to JavaScript][].
 
 **There is no need to `require` this module** since it gets preloaded into
 all sandboxes automatically.
 
 Usage of new ES5 API's is encouraged, but since not everything can be
 provided to all the versions of firefox, there are few things to be aware of:
 
-- `Object.freeze`, `Object.seal`, `Object.preventExtensions` does not really
+`Object.freeze`, `Object.seal`, `Object.preventExtensions` does not really
 prevents any mutations. One thing it guarantees though, `Object.isFrozen`,
 `Object.isSealed`, `Object.isExtensible` checks will behave as defined in
 specification.
 
-- `Object.defineProperty` is only partially compliant with specification:
-	- Non configurable properties will be created as configurable ones.
-	- Instead of non-writable properties getters and setters will be defined,
-		but `Object.getOwnPropertyDescriptor` will still behave as expected
-		(will return property descriptor for non-writable property not a getter)
-	- Defining properties using ES5 functions will break your [custom iterators]
-		 if you have any. Think twice before employing custom iterator cause in
-		 majority of cases you can just make properties non enumerable. In case
-		 you really need to have custom iterator be smart about it, make sure to
-		 add it after running ES5 functions and don't ignore previous iterators.
-		 Please see example below for inspiration:
-
-		     let object = Object.create({}, {
-		       myField: { value: 6 }
-		     });
-		     object.__iterator__ = (function(original) {
-		       return function myIterator() {
-		         this.__iterator__ = original;
-		         for (let key in this) {
-		           // your logic here
-		         }
-		         this.__iterator__ = myIterator;
-		       }
-		     })(object.__iterator__);
+`Object.defineProperty` is only partially compliant with the specification:
+
+- Non configurable properties will be created as configurable ones.
+
+- Instead of non-writable properties getters and setters will be defined,
+but `Object.getOwnPropertyDescriptor` will still behave as expected
+(will return property descriptor for non-writable property not a getter)
+
+- Defining properties using ES5 functions will break your
+     [custom iterators][] if you have any. Think twice before employing
+     custom iterators, because in most cases you can just make properties
+     non enumerable. If you really need to have a custom iterator, add it
+     after running ES5 functions and don't ignore previous iterators.
+     For example:
+
+         let object = Object.create({}, {
+           myField: { value: 6 }
+         });
+         object.__iterator__ = (function(original) {
+           return function myIterator() {
+             this.__iterator__ = original;
+             for (let key in this) {
+               // your logic here
+             }
+             this.__iterator__ = myIterator;
+           }
+         })(object.__iterator__);
 
 [custom iterators]:https://developer.mozilla.org/en/New_in_JavaScript_1.7#Iterators
 [ES5 specification]:http://www.ecmascript.org/docs/tc39-2009-043.pdf

diff --git a/packages/api-utils/docs/light-traits.md b/packages/api-utils/docs/light-traits.md
@@ -1,4 +1,3 @@
-# Traits #
 
 [Traits](http://en.wikipedia.org/wiki/Trait_%28computer_science%29) are a simple
 mechanism for structuring object-oriented programs. They represent reusable and

diff --git a/packages/api-utils/docs/traits.md b/packages/api-utils/docs/traits.md
@@ -4,9 +4,6 @@ The `traits` module provides base building blocks for secure object
 composition. It exports base trait / constructor function that
 constructs an instance of `Trait`.
 
-Traits
-------
-
 [Traits](http://en.wikipedia.org/wiki/Trait_%28computer_science%29) are a
 simple composition mechanism for structuring object-oriented programs. Traits
 are similar to

diff --git a/packages/api-utils/docs/unload.md b/packages/api-utils/docs/unload.md
@@ -4,7 +4,7 @@
 
 The `unload` module allows modules to register callbacks that are called
 when they are unloaded.  It is similar to the CommonJS module of the same
-name in the [Narwhal] platform.
+name in the [Narwhal][] platform.
 
 [Narwhal]: http://narwhaljs.org/
 

diff --git a/packages/api-utils/docs/xhr.md b/packages/api-utils/docs/xhr.md
@@ -4,28 +4,6 @@
 The `xhr` module provides access to `XMLHttpRequest` functionality, also known
 as AJAX.
 
-## Constructors ##
-
-<api name="XMLHttpRequest">
-@constructor
-  Creates an `XMLHttpRequest`. This is a constructor, so its use should always
-  be preceded by the `new` operator.  For more information about
-  `XMLHttpRequest` objects, see the MDC page on
-  [Using XMLHttpRequest](https://developer.mozilla.org/En/Using_XMLHttpRequest)
-  and the Limitations section below.
-</api>
-
-## Functions ##
-
-<api name="getRequestCount">
-@function
-  Returns the number of `XMLHttpRequest` objects that are alive (i.e., currently
-  active or about to be).
-@returns {integer}
-  The number of live `XMLHttpRequest` objects.
-</api>
-
-
 ## Limitations ##
 
 The `XMLHttpRequest` object is currently fairly limited, and does not
@@ -90,3 +68,24 @@ packaged, read-only resources.
 Finally, we need to also consider attenuating http/https requests such
 that they're "sandboxed" and don't communicate potentially sensitive
 cookie information.
+
+<api name="XMLHttpRequest">
+@class
+
+<api name="XMLHttpRequest">
+@constructor
+  Creates an `XMLHttpRequest`. This is a constructor, so its use should always
+  be preceded by the `new` operator.  For more information about
+  `XMLHttpRequest` objects, see the MDC page on
+  [Using XMLHttpRequest](https://developer.mozilla.org/En/Using_XMLHttpRequest)
+  and the Limitations section in this page.
+</api>
+</api>
+
+<api name="getRequestCount">
+@function
+  Returns the number of `XMLHttpRequest` objects that are alive (i.e., currently
+  active or about to be).
+@returns {integer}
+  The number of live `XMLHttpRequest` objects.
+</api>