Documentation (#168)

doc/tutorials/REQUIRE.md

@@ -1,43 +1,46 @@
-The library offers a way to organize the project by creating separate resources files and link them
-using dependencies. The {@see gpf.require.define} API is the main entry point. 
+The library offers a way to organize any project by creating separate resources files and reference them
+like dependencies. The {@see gpf.require.define} API is the main entry point. 
 
-A resource is referenced using its path. A resource may reference other resources using a relative path.
-For the initial call, a base path might be defined using {@see gpf.require.configure}.
-The resolved resource name correspond to the concatenation of the base path and the resource path.
+A resource file is referenced using its path. A resource may reference another resource using a path that is relative
+to the current one. For the initial call, a base path may be defined using {@see gpf.require.configure}.
+The resource resolved path correspond to the resource absolute path.
 
-Several type of resources files can be linked, type detection is based on the extension (case insensitive):
+The library handles several type of resources files. Type detection is based on the path extension (case insensitive):
 - **.json** JSON static resource file
 - **.js** JavaScript module
+- by default, any other type is handled as a text file
 
-Once a resource file is loaded, its associated output is cached using the resolved file name.
+Once a resource file is loaded, its associated output *(see below)* is cached and indexed using the resolved file path.
 Consequently (considering the cache is never cleared):
-- If the same resource is accessed twice (using relative path but with the same resolved file name),
-the file will be loaded only once
+- If the same resource (i.e. the same resolved path) is accessed twice, the file will be loaded only once
 - Any modification applied to the output will be reflected globally
 
 ## JSON static resource file
 
-A JSON file is loaded, parsed and the result object is associated to the resource name.
-
+A JSON file is loaded, parsed and the result value is the output.
 
 ## JavaScript Module
 
-resources => module or static resources
+Modules are designed to enforce best practices:
+- The module scope is private, public exposure has to be
+[explicit](https://carldanley.com/js-revealing-module-pattern/). This reduces the global namespace cluttering.
+ *(see the different supported formats below)* 
+- Dependencies are loaded first and then made available to the module through
+[injection](https://en.wikipedia.org/wiki/Dependency_injection)
 
-A module has several properties:
-- Its scope is private, it decides what is exposed
-- Dependencies are loaded first and then made available to the module
+Whatever the chosen module format, the top level call must be {@see gpf.require.define}.
+The factory function is optional and a promised is returned to know when the dependant resources are loaded.
 
-Whatever the chosen module format, the very first call must be {@see gpf.require.define}.
-The factory function is optional and a promised is returned to know whe nthe dependant modules are loaded.
-Once the initial call is made, the API supports several formats.
+The library supports several module formats. In general, the `gpf` symbol is always available.
+If you need an access to the global context, use the `{@see gpf.context}` API.
 
+### GPF Module
 
-In general, the `gpf` symbol is always available. It allows you to access the global context through the
-`{@see gpf.context}` API.
-In particular, you may define a gpf module using {@see gpf.require.define}.
+This module format is similar to the [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) one but
+it limits the number of parameters inside the factory function. Indeed, dependencies are explicitly named in a
+dictionary and consolidated with the same name in one parameter.
 
-### GPF Module
+The module public API (i.e. resource output) is the result of the factory function.
 
 ```JavaScript
 gpf.require.define({
@@ -74,7 +77,7 @@ gpf.require.define({
 
 ### Asynchronous Module Definition (AMD)
 
-The [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) format
+The library supports the [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) format.
 
 ```JavaScript
 define("amd", [
@@ -171,7 +174,8 @@ define(function () {
 
 ### CommonJS
 
-The [CommonJS](https://en.wikipedia.org/wiki/CommonJS) format:
+The library also supports the [CommonJS](https://en.wikipedia.org/wiki/CommonJS) format with one restriction.
+Only static requires can be used (i.e. the require parameter **must** be a string).
 
 ```JavaScript
 "use strict";