Doc updates, and add a test that was part of last commit.

jrburke · jrburke · commit 34ea12691f83 · 2011-06-23T15:26:46.000-07:00
diff --git a/docs/api.html b/docs/api.html
@@ -11,9 +11,10 @@ <h1>RequireJS API</h1>
                 <li class="hbox"><a href="#deffunc">Definition Functions</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.2</span></li>
                 <li class="hbox"><a href="#defdep">Definition Functions with Dependencies</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.3</span></li>
                 <li class="hbox"><a href="#funcmodule">Define a Module as a Function</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.4</span></li>
-                <li class="hbox"><a href="#modulename">Define a Module with a name</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.5</span></li>
-                <li class="hbox"><a href="#modulenotes">Other Module Notes</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.6</span></li>
-                <li class="hbox"><a href="#circular">Circular Dependencies</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.7</span></li>
+                <li class="hbox"><a href="#cjsmodule">Define a Module with Simplified CommonJS Wrapper</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.5</span></li>
+                <li class="hbox"><a href="#modulename">Define a Module with a name</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.6</span></li>
+                <li class="hbox"><a href="#modulenotes">Other Module Notes</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.7</span></li>
+                <li class="hbox"><a href="#circular">Circular Dependencies</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.2.8</span></li>
             </ul>
             <li class="hbox"><a href="#i18n">Define an I18N Bundle</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.3</span></li>
             <li class="hbox"><a href="#text">Specify a Text File Dependency</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1.4</span></li>
@@ -76,7 +77,15 @@ <h3>
 <li>b.js (in the same directory as the HTML page that has the above HTML snippet)</li>
 </ul>
 
-<p>Files that end in ".js" are assumed to just be plain JS files that do not use the RequireJS module syntax, and therefore do not use the module-to-path algorithm used for looking up dot-notation modules, like "some/module" above.</p>
+<p>RequireJS normally uses the <a href="#config-baseUrl">baseUrl</a> and <a href="#config-paths">paths</a> configuration to convert names like "some/module" into a file path.</p>
+
+<p>However, if the dependency name has one of the following properties, it is treated as a regular file path, like something that was passed to a &lt;script src=""&gt; tag:</p>
+
+<ul>
+<li>Ends in ".js".</li>
+<li>Starts with a "/".</li>
+<li>Contains an URL protocol, like "http:" or "https:".</li>
+</ul>
 
 <p>See the <a href="#config">Configuration Options</a> section for information on changing the lookup paths used for dependencies.</p>
 
@@ -218,8 +227,20 @@ <h4><a name="funcmodule">Define a Module as a Function</a><span class="sectionMa
 </code></pre>
 </div>
 
+
+<div class="subSection">
+<h4><a name="cjsmodule">Define a Module with Simplified CommonJS Wrapper</a><span class="sectionMark">&sect; 1.2.5</span></h4>
+
+<p>If you wish to reuse some code that was written in the traditional <a href="http://wiki.commonjs.org/wiki/Modules/1.1.1">CommonJS module format</a> it may be difficult to re-work to the array of dependencies used above. Also, Node 0.5 will likely support a limited kind of define() function that provides a simple wrapper over CommonJS files. So if you are building a small utility and you wish it to be used in both Node (without using the <a href="node.html">RequireJS Node adapter</a>), and in the browser, you can use the <a href="commonjs.html">simplified CommonJS wrapper</a>.</p>
+
+<p>It can also be useful if you have many dependencies, and keeping dependency array positioning in sync with the function argument positioning is undesirable.</p>
+
+<p>This wrapper relies on Function.prototype.toString() to give a useful string value of the function contents. This does not work on some devices like the PS3 and some older Opera mobile browsers. Use the <a href="optimization.html">optimizer</a> to pull out the dependencies in the array format for use on those devices.</p>
+</div>
+
+
 <div class="subSection">
-<h4><a name="modulename">Define a Module with a Name</a><span class="sectionMark">&sect; 1.2.5</span></h4>
+<h4><a name="modulename">Define a Module with a Name</a><span class="sectionMark">&sect; 1.2.6</span></h4>
 
 <p>You may encounter some define() calls that include a name for the module as the first argument to define():</p>
 
@@ -237,7 +258,7 @@ <h4><a name="modulename">Define a Module with a Name</a><span class="sectionMark
 
 <div class="subSection">
 
-<h4><a name="modulenotes">Other Module Notes</a><span class="sectionMark">&sect; 1.2.6</span></h4>
+<h4><a name="modulenotes">Other Module Notes</a><span class="sectionMark">&sect; 1.2.7</span></h4>
 
 <p><strong>One module per file.</strong>: Only one module should be defined per JavaScript file, given the nature of the module name-to-file-path lookup algorithm. Multiple modules will be grouped into optimized files by the <a href="optimization.html">optimization tool</a>, but you should only use the optimization tool to place more than one module in a file.</p>
 
@@ -266,7 +287,7 @@ <h4><a name="modulenotes">Other Module Notes</a><span class="sectionMark">&sect;
 </div>
 
 <div class="subSection">
-<h4><a name="circular">Circular Dependencies</a><span class="sectionMark">&sect; 1.2.7</span></h4>
+<h4><a name="circular">Circular Dependencies</a><span class="sectionMark">&sect; 1.2.8</span></h4>
 
 <p>If you define a circular dependency (A needs B and B needs A), then in this case when B's module function is called, it will get an undefined value for A. B can fetch A later after modules have been defined by using the require() method (be sure to specify require as a dependency so the right context is used to look up A):</p>
 
diff --git a/docs/errors.html b/docs/errors.html
@@ -20,7 +20,7 @@ <h2><a name="mismatch">Mismatched anonymous define() modules ...</a><span class=
 
 <p>Also seen if you manually code a script tag in HTML to load a script that has a few named modules, but then try to load an anonymous module that ends up having the same name as one of the named modules in the script loaded by the manually coded script tag.</p>
 
-<p>Finally, if you use the loader plugins or anonymous modules but do not use the RequireJS optimizer to combine files together, this error can occur. The optimizer knows how to name anonymous modules correctly so that can be combined with other modules in an optimized file.</p>
+<p>Finally, if you use the loader plugins or anonymous modules (modules that call define() with no string ID) but do not use the RequireJS optimizer to combine files together, this error can occur. The optimizer knows how to name anonymous modules correctly so that they can be combined with other modules in an optimized file.</p>
 
 <p>To avoid the error:</p>
 
diff --git a/docs/node.html b/docs/node.html
@@ -35,6 +35,8 @@ <h2>
 
 <p>RequireJS will use its <a href="api.html#config">Configuration Options</a> first to find modules. If RequireJS cannot find the module with its configuration, it is assumed to be a module that uses Node's type of modules and configuration. So, only configure module locations with RequireJS if they use the RequireJS API. For modules that expect Node's APIs and configuration/paths, just install them with a Node package manager, like <a href="http://npmjs.org/">npm</a>, and do not configure their locations with RequireJS.</p>
 
+<p><strong>Best practice</strong>: Use npm to install Node-only packages/modules into the projects <strong>node_modules</strong> directory, but do not configure RequireJS to look inside the node_modules directory. Also avoid using relative module IDs to reference modules that are Node-only modules. So, <strong>do not</strong> do something like <strong>require("./node_modules/foo/foo")</strong>.</p>
+
 <p>Even though RequireJS is an asynchronous loader in the browser, the RequireJS Node adapter loads modules synchronously in the Node environment to match the default loading behavior in Node.</p>
 
 <p>Finally, RequireJS in Node can only load modules that are on the local disk -- fetching modules across http, for instance, is not supported at this time.</p>
diff --git a/tasks.txt b/tasks.txt
@@ -15,17 +15,7 @@ Next release
 
 - Confirm text plugin API change is worth it.
 
-- anonymous define call 4th case:
-We found a fourth path, two calls to define() in one file.
-require-debug.js reports this error as:
-      Second anonymous define(): <the text of the second function found>
-so then you can search for the text of the second function to perhaps understand the problem.
-
 Docs:
-- http://requirejs.org/docs/api.html#jsfiles make the "plain script tag rules"
-  more of a bulleted list to call them out.
-- Update api.html#define to indicate commonjs wrapper.
-- Interaction of node_modules and paths in r.js
 - Pointer to motivations behind current thing, reason for dependencies.
 - Put page title in head's title element.
 
diff --git a/tests/configRequirejs.html b/tests/configRequirejs.html
@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>require.js: Config requirejs Test</title>
+    <script type="text/javascript" src="doh/runner.js"></script>
+    <script type="text/javascript" src="doh/_browserRunner.js"></script>
+    <script>
+        function require() {
+            return "pristine";
+        }
+
+        function done() {
+            doh.register(
+                        "config",
+                        [
+                            function config(t){
+                                t.is("pristine", require());
+                                t.is("blue", s.color);
+                                t.is("dimple-blue", d.color);
+                                t.is("You called a function", f());
+                            }
+                        ]
+                    );
+            doh.run();
+        }
+
+        var s, d, f,
+            requirejs = {
+                baseUrl: "./",
+                deps: ["require", "simple", "dimple", "func"],
+                callback: function (require, simple, dimple, func) {
+                    s = simple;
+                    d = dimple;
+                    f = func;
+                },
+                ready: function() {
+                    done();
+                }
+            };
+    </script>
+    <script type="text/javascript" src="../require.js"></script>
+</head>
+<body>
+    <h1>require.js: Config requirejs Test</h1>
+    <p>Tests requirejs being defined as an object with init and ready configuration.</p>
+    <p>Check console for messages.</p>
+</body>
+</html>
