Merge pull request #142 from stasm/jsdoc

Bug 1303148 - Use a documentation generator

docs/localization.md

@@ -1,37 +1,59 @@
-The Localization API
---------------------
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-The `Localization` class is responsible for fetching resources and formatting 
-translations.
+# Localization
 
-l20n.js for HTML will create an instance of `Localization` for the default set 
-of `<link rel="localization">` elements.  You can get a reference to it via:
+The `Localization` class is responsible for fetching resources and 
+formatting translations.
 
-```javascript
-const localization = document.l10n.get('main');
-```
+l20n.js for HTML will create an instance of `Localization` for the default 
+set of `<link rel="localization">` elements.  You can get a reference to it 
+via:
+
+    const localization = document.l10n.get('main');
 
 Different names can be specified via the `name` attribute on the `<link>` 
 elements.
 
+## constructor
+
+**Parameters**
+
+-   `requestBundles` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
+-   `createContext`  
 
-### Localization.interactive
+Returns **[Localization](#localization)** 
 
-A Promise which resolves when the `Localization` instance has fetched and 
-parsed all localization resources in the user's first preferred language (if 
-available).
+## formatValues
+
+A generalized version of `Localization.formatValue`.  Retrieve 
+translations corresponding to the passed keys.  Keys can either be simple 
+string identifiers or `[id, args]` arrays.
+
+Returns a Promise resolving to an array of the translation strings.
 
 ```javascript
-localization.interactive.then(callback);
+document.l10n.formatValues(
+  ['hello', { who: 'Mary' }],
+  ['hello', { who: 'John' }],
+  'welcome'
+).then(([helloMary, helloJohn, welcome]) =>
+  console.log(helloMary, helloJohn, welcome)
+);
+// -> 'Hello, Mary!', 'Hello, John!', 'Welcome!'
 ```
 
+**Parameters**
+
+-   `keys` **...any** 
 
-### Localization.formatValue(id, args)
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 
+
+## formatValue
 
 Retrieve the translation corresponding to the `id` identifier.
 
-If passed, `args` is a simple hash object with a list of variables that will be 
-interpolated in the value of the translation.
+If passed, `args` is a simple hash object with a list of variables that 
+will be interpolated in the value of the translation.
 
 Returns a Promise resolving to the translation string.
 
@@ -41,24 +63,134 @@ localization.formatValue('hello', { who: 'world' }).then(
 // -> 'Hello, world!'
 ```
 
-Use this sparingly for one-off messages which don't need to be retranslated 
-when the user changes their language preferences.
+Use this sparingly for one-off messages which don't need to be 
+retranslated when the user changes their language preferences.
 
+**Parameters**
 
-### Localization.formatValues(...keys)
+-   `id`  
+-   `args`  
 
-A generalized version of `Localization.formatValue`.  Retrieve translations 
-corresponding to the passed keys.  Keys can either be simple string identifiers 
-or `[id, args]` arrays.
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 
 
-Returns a Promise resolving to an array of the translation strings.
+# LocalizationObserver
+
+The `LocalizationObserver` class is responsible for localizing DOM trees.  
+It also implements the iterable protocol which allows iterating over and 
+retrieving available `Localization` objects.
+
+Each `document` will have its corresponding `LocalizationObserver` instance 
+created automatically on startup, as `document.l10n`.
+
+## constructor
+
+Returns **[LocalizationObserver](#localizationobserver)** 
+
+## get
+
+Retrieve a reference to the `Localization` object associated with the name 
+`name`.  See [docs/localization] for `Localization`'s API reference.
 
 ```javascript
-document.l10n.formatValues(
-  ['hello', { who: 'Mary' }],
-  ['hello', { who: 'John' }],
-  'welcome'
-).then(([helloMary, helloJohn, welcome]) =>
-  console.log(helloMary, helloJohn, welcome));
-// -> 'Hello, Mary!', 'Hello, John!', 'Welcome!'
+const mainLocalization = document.l10n.get('main');
+const extraLocalization = document.l10n.get('extra');
+```
+
+**Parameters**
+
+-   `name`  
+
+Returns **[Localization](#localization)** 
+
+## requestLanguages
+
+Trigger the language negotation process with an array of `langCodes`.  
+Returns a promise with the negotiated array of language objects as above.
+
+```javascript
+document.l10n.requestLanguages(['de-DE', 'de', 'en-US']);
+```
+
+**Parameters**
+
+-   `requestedLangs`  
+
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 
+
+## setAttributes
+
+Set the `data-l10n-id` and `data-l10n-args` attributes on DOM elements.
+L20n makes use of mutation observers to detect changes to `data-l10n-*`
+attributes and translate elements asynchronously.  `setAttributes` is 
+a convenience method which allows to translate DOM elements declaratively.
+
+You should always prefer to use `data-l10n-id` on elements (statically in 
+HTML or dynamically via `setAttributes`) over manually retrieving 
+translations with `format`.  The use of attributes ensures that the 
+elements can be retranslated when the user changes their language 
+preferences.
+
+```javascript
+document.l10n.setAttributes(
+  document.querySelector('#welcome'), 'hello', { who: 'world' }
+);
+```
+
+This will set the following attributes on the `#welcome` element.  L20n's 
+MutationObserver will pick up this change and will localize the element 
+asynchronously.
+
+```html
+<p id='welcome'
+  data-l10n-id='hello'
+  data-l10n-args='{"who": "world"}'>
+</p>
+```
+
+**Parameters**
+
+-   `element`  
+-   `id`  
+-   `args`  
+
+## getAttributes
+
+Get the `data-l10n-*` attributes from DOM elements.
+
+```javascript
+document.l10n.getAttributes(
+  document.querySelector('#welcome')
+);
+// -> { id: 'hello', args: { who: 'world' } }
+```
+
+**Parameters**
+
+-   `element`  
+
+Returns **{id: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), args: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)}** 
+
+## translateFragment
+
+Translate a DOM node or fragment asynchronously.
+
+You can manually trigger translation (or re-translation) of a DOM fragment 
+with `translateFragment`.  Use the `data-l10n-id` and `data-l10n-args` 
+attributes to mark up the DOM with information about which translations to 
+use.
+
+**Parameters**
+
+-   `frag`  
+
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 
+
+# interactive
+
+A Promise which resolves when the `Localization` instance has fetched 
+and parsed all localization resources in the user's first preferred 
+language (if available).
+
+```javascript
+localization.interactive.then(callback);
 ```

makefile

@@ -8,7 +8,6 @@ all: lint build
 
 build: $(RUNTIMES)
 
-.PHONY: $(RUNTIMES)
 $(RUNTIMES):
 	@$(MAKE) -s -C $@
 	@echo -e " $(OK) $@ built"
@@ -31,4 +30,10 @@ test-lib:
 test-browser:
 	karma start test/karma.conf.js
 
+docs:
+	documentation build --shallow -f md \
+	    src/lib/**/*.js > docs/localization.md
+
+.PHONY: $(RUNTIMES) docs
+
 include tools/perf/makefile

package.json

@@ -188,5 +188,8 @@
       "prefer-rest-params": 2,
       "no-cond-assign": 2
     }
+  },
+  "dependencies": {
+    "documentation": "^4.0.0-beta10"
   }
 }