docs update for #6.x #3

anodynos · Sep 30, 2013 · d9a74e8 · d9a74e8
1 parent 0821b2c
commit d9a74e8
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 47 deletions.
diff --git a/source/code/config/MasterDefaultsConfig.coffee.md b/source/code/config/MasterDefaultsConfig.coffee.md
@@ -15,9 +15,9 @@ NOTE: This file primary location is https://github.com/anodynos/uRequire/blob/ma
 A `config` determines a `bundle` and a `build` that uRequire will process. A config is an object with the expected keys and can be used as:
 
 * **File based**, using the urequire CLI (from `npm install urequire -g`) as `$ urequire config myConfig.js`, where `myConfig.js` is a node module file that exports the `config` object. The file can actually be a `.coffee` or `.js` node module, or a `.json` file as well as many other formats - see [butter-require](https://github.com/anodynos/butter-require).
- The value of an 'XXX' ['derive'](#derive)d parent in a file-based config can be another file `configFilename.yml`, relative to the 1st children's path. @todo: make relative to each children's path).
+ The value of an 'XXX' ['derive'](#deriving)d parent in a file-based config can be another file (eg `configFilename.yml`), relative to the 1st children's path. @todo: make relative to each children's path).
 
-* Using [**grunt-urequire**](https://github.com/aearly/grunt-urequire), having (almost) the exact `config` object of the file-base, but as a `urequire:XYZ` grunt task. The main difference is that a XXX ['derive'](#derive)d parent in grunt-urequire config can be another `urequire:XXX` task, and if none is found then its assumed to be a filename, relative to grunt's config.
+* Using [**grunt-urequire**](https://github.com/aearly/grunt-urequire), having (almost) the exact `config` object of the file-base, but as a `urequire:XYZ` grunt task. The main difference is that a XXX ['derive'](#deriving)d parent in grunt-urequire config can be another `urequire:XXX` task, and if none is found then its assumed to be a filename, relative to grunt's config.
 
 * Within your tool's code, [using `urequire.BundleBuilder`](Using-uRequire#Using-within-your-code).
 
@@ -711,8 +711,9 @@ uberscore:
     root: 'uberscore': '_B'
 
   resources: [
-     # as comments cause literate coffeescript considers
-     # indented lines as code, even in ` ` ` blocks
+
+#    # as comments cause literate coffeescript considers
+#    # indented lines as code, even in ` ` ` blocks
 
 #    [ '~+inject:VERSION', ['uberscore.coffee'],
 #      (m)-> m.beforeBody = "var VERSION='#{pkg.version}';"]
@@ -745,8 +746,10 @@ The `'urequire:min'` task :
    dependencies: exports: bundle: [
      [null], 'underscore', 'agreement/isAgree']
    resources: [
-#       # as comments cause literate coffeescript considers
-#       # indented lines as code, even in ` ` ` blocks
+
+#     # as comments cause literate coffeescript considers
+#     # indented lines as code, even in ` ` ` blocks
+
 #     [
 #       '+remove:debug/deb & deepExtend', [/./]
 #

diff --git a/source/code/config/ResourceConverters.coffee.md b/source/code/config/ResourceConverters.coffee.md
@@ -415,8 +415,11 @@ For example :
 resources: [
   ...
   [
-    '+remove:debug/deb', [/./]                              
-    function(modyle){ modyle.replaceCode('if (l.deb()){}');}                      
+    '+remove:debug/deb', [/./]
+
+    # perform the replacement / deletion
+    # note: return value is ignored in '+' `isBeforeTemplate` RCs
+    (modyle)-> modyle.replaceCode 'if (l.deb()){}'
   ]
   ...  
 ]
@@ -440,7 +443,10 @@ will remove all code that matches the `'if (l.deb()){}'` skeleton.
 
 For example 
 ```
-  module.injectDeps({ 'lodash':'_', 'models/Person':['persons', 'personsModel']})
+  module.injectDeps({
+    'lodash': '_',
+    'models/Person': ['persons', 'personsModel']
+  });
 ```  
 
 The deps are (the keys of the object) are always given in [bundleRelative](#bundlerelative-vs-filerelative-paths) format.
@@ -468,22 +474,33 @@ The following code [(that is actually part of uRequire's code)](#Literate-Coffes
 This is a dummy .js RC, following the [formal RC definition](#Inside-a-Resource-Converter):
 
         {
-          name: '$javascript'             # '$' flag denotes `type: 'module'`.
+          # name - with a '$' flag to denote `type: 'module'`.
+          name: '$javascript'
+
+          descr: "Dummy js converter, justs marks `.js` files as `Module`s."
 
-          descr: "Dummy js converter, does nothing much but marking `.js` files as `Module`s."
+          # type is `bundle.filez`, matches files RC deals with
+          filez: [
+            # minimatch string, with exclusions as '!**/*temp.*'
+            '**/*.js'
 
-          filez: [                        # type is `bundle.filez`, matches files RC is attached to
-            '**/*.js'                     # minimatch string, with exclusions as '!**/*temp.*'
-                                          # RegExps work as well, with[.., `'!', /myRegExp/`] for exclusions
+            # RegExps as well, with[.., `'!', /myRegExp/`] for exclusions
             /.*\.(javascript)$/
+
+
+            # a `function(filename){}` also valid, with '!' for exclusion
           ]
 
-          convert: (r)-> r.source         # javascript needs no compilation - just return source as is
+          # javascript needs no compilation - returns source as is
+          # could have `undefined` in its place
+          convert: (r)-> r.source
 
-          convFilename: (srcFilename)->   # convert .js | .javascript to .js
+          # convert .js | .javascript to .js
+          convFilename: (srcFilename)->
             (require '../paths/upath').changeExt srcFilename, 'js'
 
-          type: 'module'                  # not needed, we have '$' flag to denote `type: 'module'`
+          # not needed, we have '$' flag to denote `type: 'module'`
+          type: 'module'
 
           # these are defaults, can be omitted
           isAfterTemplate: false
@@ -496,34 +513,57 @@ This is a dummy .js RC, following the [formal RC definition](#Inside-a-Resource-
 This RC is using an [] instead of {}. Key names of RC are assumed from their posision in the array:
 
         [
-          '$coffee-script'                                           # `name` & flags as a String at pos 0
+          # `name` & flags as a String at pos 0
+          '$coffee-script'
+
+          # `descr` at pos 1
+          "Coffeescript compiler, using locally installed 'coffee-script'."
 
-                                                                     # `descr` at pos 1
-          "Coffeescript compiler, using the locally installed 'coffee-script' npm package. Uses `bare:true`."
+          # `filez` [] at pos 2
+          [ '**/*.coffee', /.*\.(coffee\.md|litcoffee)$/i]
 
-          [ '**/*.coffee', /.*\.(coffee\.md|litcoffee)$/i]           # `filez` [] at pos 2
+          # `convert` Function at pos 3
+          (r)->
+             # 'coffee-script' must be in 'node_modules',
+             # only if any 'coffee' file matches
+             coffee = require 'coffee-script'
 
-          (r)->                                                      # `convert` Function at pos 3
-             coffee = require 'coffee-script'                        # 'coffee-script' must be in 'node_modules'
-             coffee.compile r.source                                 # return converted source
+             # return converted source
+             coffee.compile r.source
 
-          (srcFn)->                                                  # `convFilename` Function at pos 4
-            coffeeExtensions = /.*\.(coffee\.md|litcoffee|coffee)$/  # RexExp for all coffeescript extensions
-            ext = srcFn.replace coffeeExtensions , "$1"              # retrieve matched extension
-            srcFn.replace (new RegExp ext+'$'), 'js'                 # replace it and return new filename
+          # `convFilename` Function at pos 4
+          (srcFn)->
+
+            # RexExp for all coffeescript extensions
+            coffeeExtensions =   /.*\.(coffee\.md|litcoffee|coffee)$/
+
+            # retrieve matched extension
+            ext = srcFn.replace coffeeExtensions , "$1"
+
+            # replace it and return new filename
+            srcFn.replace (new RegExp ext+'$'), 'js'
         ]
 
 ### The alternative, even shorter `[]` way
 
         [
-          '$LiveScript'                                    # `name` at pos 0
-          [ '**/*.ls']                                     # if pos 1 is Array, its `filez` (& undefined `descr`)
-          (r)->(require 'LiveScript').compile r.source     # `convert` Function at pos 2
-          '.js'                                            # if `convFilename` is String starting with '.',
-        ]                                                  # it denotes an extension replacement of `dstFilename`
-                                                           # if `~` flag is used, eg `~.js`, ext replacement is applied on `srcFilename`
+          '$LiveScript'
+
+          # if pos 1 is Array, its `filez` (& undefined `descr`)
+          [ '**/*.ls']
 
-### The shortest way ever, a one-liner converter!
+          # `convert` Function at pos 2
+          (r)->(require 'LiveScript').compile r.source
+
+          # if `convFilename` is String starting with '.',
+          # it denotes an extension replacement of `dstFilename`
+          # if `~` flag was used, eg `~.js`, ext replacement
+          # would be applied on `srcFilename`
+          '.js'
+        ]
+
+
+### The shortest way ever, one-liner, no comments converters!
 
         [ '$iced-coffee-script', [ '**/*.iced'], ((r)-> require('iced-coffee-script').compile r.source), '.js']
 
@@ -549,26 +589,38 @@ To save loading & processing time, these RC-specs aren't instantiated as proper
          '@~teacup'
          """
           Renders teacup as nodejs modules (exporting the template function or a `renderable`), to HTML.
-          FileResource means the file's source is not read/refreshed.
+          `FileResource` means the file's source is not read on resource.refresh().
          """
          ['**/*.teacup']
+
+         # our `convert()` function is a Immediate Function Invocation
+         # that returns the real `convert` fn.
          do ->
-            require.extensions['.teacup'] = 
-                require.extensions['.coffee']              # register extension once, as a node/coffee module
-            (r)->                                          # our `convert()` function
-              template = r.requireUncached r.srcRealpath   # Clear nodejs caching with `requireUncached` helper 
-                                                           # and get the `realpath` of module's location.
-              (require 'teacup').render template           # require `teacup` on demand from project's 
-                                                           # `node_modules` and return rendered string
-                                                            
-         '.html'                                           # starting with '.' is an extension replacement
+            # register extension once, as a node/coffee module
+            require.extensions['.teacup'] = require.extensions['.coffee']
+
+            # our real, IFI returned `convert()` function
+            (r)->
+              # Clear nodejs caching with `requireUncached` helper
+              # and get the `realpath` of module's location.
+              template = r.requireUncached r.srcRealpath
+
+              # require `teacup` on demand from project's `node_modules`
+              # and return rendered string
+              (require 'teacup').render template
+
+         # starting with '.' is an extension replacement
+         '.html'
       ]
 
 # Finito 
 
 Just export default and extra RCs and go grab a cup of coffee!
 
     module.exports = {
-      defaultResourceConverters       # used as is by `bundle.resources`
-      extraResourceConverters         # registered on `ResourceConverter` registry, instantiated on demand.
+      # used as is by `bundle.resources`
+      defaultResourceConverters
+
+      # registered on `ResourceConverter` registry, instantiated on demand.
+      extraResourceConverters
     }