enhance documentation

clmath · clmath · commit 91b16cf7ba61 · 2015-01-22T19:00:59.000+01:00
diff --git a/docs/css.md b/docs/css.md
@@ -1,20 +1,23 @@
 ---
-layout: default
+layout: doc
 title: requirejs-dplugins/css
 ---
 
 # requirejs-dplugins/css!
 
 This plugin will load and wait for a css file. This can be handy to load the css
-specific to a widget.
+specific to any AMD module (like a widget) .
 
-CSS loaded with this plugin can be overwritten by user-defined style sheet, using `<link>` or `<style>` tag.
+This plugin uses `<link>` tags to load CSS files and those tags are inserted as the first child of the
+`<head>` tag. This guarantees that CSS loaded with this plugin will not overwrite CSS inserted manually using
+ `<link>` or `<style>` tag.
 
 This plugin will return the path of the inserted css file relative to requirejs baseUrl.
 
 ## Example
 
 To load the css file `myproj/comp.css` you can use:
+
 ```
 require(["requirejs-dplugins/css!myproj/comp.css"], function (){
 	// Code placed here will wait for myproj/comp.css before running.
@@ -29,3 +32,8 @@ define(["requirejs-dplugins/css!myproj/comp.css"], function (){
 });
 ```
 
+## Build
+
+During the build, this plugin will collect all the CSS files required and create a layer with all the CSS
+files concatenated. This layer will be optimized using
+[clean-css](https://github.com/jakubpawlowicz/clean-css) if it is installed.
diff --git a/docs/has.md b/docs/has.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc
 title: requirejs-dplugins/has
 ---
 
@@ -10,13 +10,14 @@ title: requirejs-dplugins/has
 
 It is based on the conventions in the [has.js project](https://github.com/phiggins42/has.js).
 
-Note: This plugin does NOT include any feature tests.
+__Note:__ This plugin does NOT include any feature tests.
 
 ##### Table of Contents
 [Features](#features)  
 [Adding tests](#adding-tests)  
 [Use as module](#use-as-module)  
 [Use as plugin](#use-as-plugin)  
+[Build](#build)  
 
 <a name="features"></a>
 ## Features
@@ -58,6 +59,7 @@ define(["requirejs-dplugins/has"], function (has) {
 });
 ```
 
+<a name="using-static-configuration"></a>
 ### Using static configuration
 
 The plugin will look for static configuration in a hashmap provided through
@@ -101,9 +103,11 @@ Note that `moduleA` and `moduleB` are optional and if the expression doesn't res
 `undefined`.
 
 Ternary operation can be chained to run another test if the first one fails.
+
 ```
 test1?moduleA:test2?moduleB:moduleC
 ```
+
 If `test1` is true, the plugin loads `moduleA`.
 If `test1` is false but `test2` is true, the plugin loads `moduleB`.
 If `test1` is false and `test2` is false, the plugin loads `moduleC`.
@@ -114,3 +118,11 @@ define(["requirejs-dplugins/has!bidi?./bidiWidget:./Widget"], function (widget)
 	// Do something with the widget
 });
 ```
+
+<a name="build"></a>
+## Build
+
+Has flag can be specified at build time using the [static configuration](#using-static-configuration).
+If a flag is `undefined` at build time, then all the possible modules will be added to the layer.
+If a flag was set to `true` or `false`, the build will resolve the ternary condition and include only the
+needed modules in the layer.
diff --git a/docs/i18n.md b/docs/i18n.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc
 title: requirejs-dplugins/i18n
 ---
 
@@ -20,15 +20,17 @@ title: requirejs-dplugins/i18n
 If an application is not built, this plugin will behave exactly like RequireJS i18n plugin.
 The only difference is the way they build i18n bundles.
 
-While RequireJS i18n plugin adds bundles of a specified locale to the layer,
+While RequireJS i18n plugin adds bundles of a specified locale to the common layer,
 `requirejs-dplugins/i18n` will create specific nls layers for each locale specified in the `localesList` option. The
 plugin will then load the appropriate nls layer depending on the user locale.
 
 
 <a name="creating-an-i18n-bundle"></a>
 ## Creating an i18n bundle
 
-Assume a `my` package, containing a `lamp` module. This module provides a string representing the color of the lamp.
+Assume a `my` package, containing a `lamp` module. This module provides a string representing the color of
+ the lamp.
+
 ```js
 // my/lamp.js
 define([], function() {
@@ -60,6 +62,7 @@ define({
 ```
 
 This leads to the following directory structure:
+
 ```
 └── my/
     ├── nls/
@@ -106,6 +109,7 @@ define({
 ```
 
 And the following directory structure:
+
 ```
 └── my/
     ├── nls/
@@ -119,6 +123,7 @@ And the following directory structure:
 * The plugin uses the browser's `navigator.language` or `navigator.userLanguage` property to determine the required
 locale. Then it selects the most suitable locale from the root bundle. The locale can also be set using
 RequireJS config:
+
 ```
 require.config({
 	config: {
@@ -142,6 +147,7 @@ Once the `nls` bundle is setup, the plugin can be used to load the bundle. There
 * `requirejs-dplugins/i18n!./nls/locale/bundle` loads the bundle for the `locale` specified in the path.
 
 In the previous setup, if one want to display the color in a user's locale, `my/lamp` need to be updated to:
+
 ```js
 // my/lamp.js
 define(["requirejs-plugins/i18n!./nls/colors"], function(colors) {
@@ -164,6 +170,7 @@ During a build, all i18n bundles required by modules from a layer are concatenat
 `nls/layername_locale.js`.
 
 In the previous setup, building a layer `my` containing `my/lamp` results in:
+
 ```
 └── my/
     ├── nls/
@@ -222,6 +229,7 @@ Layers can be used in various situation so the plugin offers three options to ad
 In this situation, individual bundles are not deployed so the i18n plugin should not look for them.
 
 Hence the runtime configuration should be:
+
 ```
 requirejs.config({
     config: {
@@ -237,6 +245,7 @@ requirejs.config({
 In this situation, some individual bundles are deployed but not those already included in a layer.
 
 Hence the runtime configuration should be:
+
 ```
 requirejs.config({
     config: {
@@ -253,6 +262,7 @@ Runtime environment is low-latency so the `languagePack` option can be used to a
 in the future.
 
 Hence the runtime configuration should be:
+
 ```
 requirejs.config({
     config: {
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,7 @@
 ---
-layout: doc
+layout: docMain
 ---
-Requirejs-dplugins provides a set of AMD plugins compatible with requirejs.
+Requirejs-dplugins provides a set of AMD plugins compatible with requirejs and grunt-amd-build.
 
 ## Plugins
 
diff --git a/docs/jquery.md b/docs/jquery.md
@@ -1,12 +1,12 @@
 ---
-layout: default
+layout: doc
 title: requirejs-dplugins/jquery
 ---
 
 # requirejs-dplugins/jquery!
 
 
-This plugin will load load the specified jQuery module(s), unless the application has loaded the whole jQuery
+This plugin will load load the specified jQuery AMD module(s), unless the application has loaded the whole jQuery
 library via a `<script>` tag, in which case it just returns a pointer to the already loaded jQuery.
 
 It's useful to avoid loading jQuery twice.
@@ -26,3 +26,26 @@ require(["requirejs-dplugins/jquery!attributes/classes,effects"], function ($) {
     $(myNode).animate(...);
 });
 ```
+
+## Build
+This plugin needs the following AMD loader configuration to work at build time:
+
+```js
+{
+	map: {
+		jquery: {
+			"jquery/src/selector": "jquery/src/selector-native"     // don't pull in sizzle
+		}
+	}
+}
+```
+
+If the build of this plugin is enabled, it will add the needed AMD jQuery modules to the layer.
+If you don't want to include jQuery modules you can add this plugin to the `runtimePlugins` array in
+`grunt-amd-build` configuration like this:
+
+```js
+{
+	runtimePlugins: ["requirejs-dplugins/jquery"]
+}
+```
diff --git a/docs/maybe.md b/docs/maybe.md
@@ -1,12 +1,17 @@
 ---
-layout: default
+layout: doc
 title: requirejs-dplugins/maybe
 ---
 
 # requirejs-dplugins/maybe
 
 `requirejs-dplugins/maybe` allows to require modules that may or may not exist.
-If the module is not found, there is an expected 404 in the console and the module will be `undefined`.
+If the module is not found, the loader will not crash (like it would do without this plugin) but there is an
+expected 404 and the return value for the module will be `undefined`.
+
+__Note:__ You should use this plugin with caution as requiring multiple nonexistent files will have an impact on
+performances.
+
 
 ## Sample
 ```
@@ -18,3 +23,8 @@ require(["requirejs-dplugins/maybe!a/module/id"], function(module){
     }
 });
 ```
+
+## Build
+
+This plugin is not doing anything special at the build. Nothing is added to the layer even if the module
+exists.
