Normalized line endings across all articles and ported @lends documentation

Jake/articles/tags-lends

@@ -0,0 +1,111 @@
+<!--{
+    "title":       "@lends",
+    "out":         "tags-lends.html",
+    "description": "Document properties on an object literal as if they belonged to an object with a given name"
+}-->
+<h3>Syntax</h3>
+
+<code>@lends &lt;namepath></code>
+
+<h3>Overview</h3>
+
+<p>
+	The <code>@lends</code> tag allows you to document all the members of an anonymous object literal as if they 
+	were members of an object with the given name. You might want to do this if you were passing an anonymous 
+	object literal into a function that creates a named class from its members
+</p>
+
+<h3>Examples</h3>
+
+<p>
+	In this example we want to use a helper function to make a class named "Person," along with instance 
+	methods named "initialize" and "say." This is similar to how some popular frameworks handle class creation.
+</p>
+
+{{#example}} Example class
+// we want to document this as being a class
+var Person = makeClass(
+    // we want to document these as being methods
+    {
+        initialize: function(name) {
+            this.name = name;
+        },
+        say: function(message) {
+            return this.name + " says: " + message;
+        }
+    }
+);
+{{/example}}
+
+<p>
+	Without any doc comments JSDoc won't automatically recognize either a class named "Person" nor it's 
+	two methods. To document the methods we must use a "@lends" tag in a doc comment immediately before the 
+	object literal to tell JSDoc that all the member names of that object literal are being "lent" to a 
+	variable named "Person."
+</p>
+
+{{#example}} Documented as static methods
+/** @class */
+var Person = makeClass(
+    /** @lends Person */
+    {
+        initialize: function(name) {
+            this.name = name;
+        },
+        say: function(message) {
+            return this.name + " says: " + message;
+        }
+    }
+);
+{{/example}}
+
+<p>
+	Now the functions named "initialize" and "say" will be documented, but they appear as static methods of an 
+	class named "Person." That is possibly what you meant, but in this case we want "initialize" and "say" to 
+	belong to the instances of the "Person" class. So we change things slightly by lending the methods to the 
+	class's prototype:
+</p>
+
+{{#example}} Documented as instance methods
+/** @class */
+var Person = makeClass(
+    /** @lends Person.prototype */
+    {
+        initialize: function(name) {
+            this.name = name;
+        },
+        say: function(message) {
+            return this.name + " says: " + message;
+        }
+    }
+);
+{{/example}}
+
+<p>
+	If you are using one of the lent functions to construct the class, you can mark it as such using the 
+	@constructs tag, but remember to remove the @class tag in that case, or else two @classes will be documented.
+</p>
+
+{{#example}} Documented constructor
+var Person = makeClass(
+    /**
+      @lends Person.prototype
+    */
+    {
+        /** @constructs */
+        initialize: function(name) {
+            this.name = name;
+        },
+        say: function(message) {
+            return this.name + " says: " + message;
+        }
+    }
+);
+{{/example}}
+
+<h3>See Also</h3>
+
+<ul>
+    <li><a href="tags-borrows.html">@borrows</a></li>
+    <li><a href="tags-constructs.html">@constructs</a></li>
+</ul>

Jakefile.js

@@ -50,7 +50,7 @@ task('default', [], function (params) {
     console.log('Building new gh-pages...');
 
     articles.forEach(function (article) {
-        var html = Mustache.to_html(
+        var html = convertEOL(Mustache.to_html(
                 templates.article, {
                 title : article.title,
                 description : article.description,
@@ -69,7 +69,7 @@ task('default', [], function (params) {
                 head : templates.head,
                 foot : templates.foot,
                 article : article.body
-            });
+            }), '\n');
 
         fs.writeFileSync(outdir + article.out, html, 'utf8');
         console.log('> created ' + outdir + article.out);

about-getting-started.html

@@ -175,23 +175,23 @@
 
 	<article>
 	<h1>Getting Started with JSDoc 3</h1>
-
-<h3>Getting Started</h3>
-
-<p>
-JSDoc 3 is an API documentation generator for JavaScript, similar to JavaDoc or PHPDoc. You add documentation comments directly to your source code, right along side the code itself. The JSDoc Tool will scan your source code, and generate a complete HTML documentation website for you.
-</p>
-
-<h3>Adding Documentation Comments to Your Code</h3>
-
-<p>
-JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like: namespaces, classes, methods, method parameters, etc.
-</p>
-
-<p>
-JSDoc comments should generally be placed immediately before the code being documented. It must start with a <code>/**</code> sequence in order to be recognized by the JSDoc parser. Comments beginning with <code>/*</code>, <code>/***</code>, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.
-</p>
-
+
+<h3>Getting Started</h3>
+
+<p>
+JSDoc 3 is an API documentation generator for JavaScript, similar to JavaDoc or PHPDoc. You add documentation comments directly to your source code, right along side the code itself. The JSDoc Tool will scan your source code, and generate a complete HTML documentation website for you.
+</p>
+
+<h3>Adding Documentation Comments to Your Code</h3>
+
+<p>
+JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like: namespaces, classes, methods, method parameters, etc.
+</p>
+
+<p>
+JSDoc comments should generally be placed immediately before the code being documented. It must start with a <code>/**</code> sequence in order to be recognized by the JSDoc parser. Comments beginning with <code>/*</code>, <code>/***</code>, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.
+</p>
+
 <dl class="example">
 <dt>The simplest documentation is just a description.</dt>
 <dd>
@@ -202,14 +202,14 @@ <h3>Adding Documentation Comments to Your Code</h3>
 
 </pre>
 </dd>
-</dl><p>
-Adding a description is simple, just type the description you want in the documentaton comment.
-</p>
-
-<p>
-Special "documentation tags" can be used to give more information. For example, if the function is a constructor, you can indicate this by adding a tag.
-</p>
-
+</dl><p>
+Adding a description is simple, just type the description you want in the documentaton comment.
+</p>
+
+<p>
+Special "documentation tags" can be used to give more information. For example, if the function is a constructor, you can indicate this by adding a tag.
+</p>
+
 <dl class="example">
 <dt>Use a documentation tag to describe your code.</dt>
 <dd>
@@ -223,10 +223,10 @@ <h3>Adding Documentation Comments to Your Code</h3>
 
 </pre>
 </dd>
-</dl><p>
-More tags can be used to add more information. See the Tag Dictionary for a complete list of tags that are recognized by JSDoc 3.
-</p>
-
+</dl><p>
+More tags can be used to add more information. See the Tag Dictionary for a complete list of tags that are recognized by JSDoc 3.
+</p>
+
 <dl class="example">
 <dt>Adding more information with tags.</dt>
 <dd>
@@ -242,16 +242,16 @@ <h3>Adding Documentation Comments to Your Code</h3>
 
 </pre>
 </dd>
-</dl><h3>Generating A Website</h3>
-
-<p>
-Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.
-</p>
-
-<p>
-By default, JSDoc will use the "default" template to turn the documentation data into HTML. You can edit this template to suit your own needs, or create an entirely new template if that is what you prefer.
-</p>
-
+</dl><h3>Generating A Website</h3>
+
+<p>
+Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.
+</p>
+
+<p>
+By default, JSDoc will use the "default" template to turn the documentation data into HTML. You can edit this template to suit your own needs, or create an entirely new template if that is what you prefer.
+</p>
+
 <dl class="example">
 <dt>Running the documentation generator on the command line.</dt>
 <dd>
@@ -260,8 +260,8 @@ <h3>Adding Documentation Comments to Your Code</h3>
 
 </pre>
 </dd>
-</dl><p>
-This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.
+</dl><p>
+This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.
 </p>
     </article>
 
@@ -274,3 +274,4 @@ <h3>Adding Documentation Comments to Your Code</h3>
 	<script>prettyPrint()</script>
 </body>
 </html>
+

about-including-readme.html

@@ -175,11 +175,11 @@
 
 	<article>
 	<h1>Including a Readme File With JSDoc 3</h1>
-
-<h3>Including a Readme File in Your Documentation With JSDoc 3</h3>
-
-<p>To include a readme file in your documentation, you simply specify the location of your readme file on the command line along with the location of your source files. The readme file will be incorporated into the index.html of your documentation in the default template. The file must be written in markdown and given a .md extension.</p>
-
+
+<h3>Including a Readme File in Your Documentation With JSDoc 3</h3>
+
+<p>To include a readme file in your documentation, you simply specify the location of your readme file on the command line along with the location of your source files. The readme file will be incorporated into the index.html of your documentation in the default template. The file must be written in markdown and given a .md extension.</p>
+
 <dl class="example">
 <dt>Including a readme file in your documentation</dt>
 <dd>
@@ -188,7 +188,7 @@ <h3>Including a Readme File in Your Documentation With JSDoc 3</h3>
 
 </pre>
 </dd>
-</dl><p>If your file is successfully incorporated into the default template, it's content will be rendered in beautiful HTML just before the files list.</p>
+</dl><p>If your file is successfully incorporated into the default template, it's content will be rendered in beautiful HTML just before the files list.</p>
 
     </article>
 
@@ -201,3 +201,4 @@ <h3>Including a Readme File in Your Documentation With JSDoc 3</h3>
 	<script>prettyPrint()</script>
 </body>
 </html>
+

about-jsdoc3.html

@@ -365,3 +365,4 @@ <h2>
 	<script>prettyPrint()</script>
 </body>
 </html>
+

about-license-jsdoc3.html

@@ -315,3 +315,4 @@ <h2>TaffyDB</h2>
 	<script>prettyPrint()</script>
 </body>
 </html>
+

about-namepaths.html

@@ -175,13 +175,13 @@
 
 	<article>
 	<h1>Using namepaths with JSDoc 3</h1>
-
-<h3>Namepaths in JSDoc 3</h3>
-
-<p>
-When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables.
-</p>
-
+
+<h3>Namepaths in JSDoc 3</h3>
+
+<p>
+When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables.
+</p>
+
 <dl class="example">
 <dt>Basic Syntax Examples of Nameptahs in JSDoc 3</dt>
 <dd>
@@ -194,10 +194,10 @@ <h3>Namepaths in JSDoc 3</h3>
 
 </pre>
 </dd>
-</dl><p>
-The example below shows: an <em>instance</em> method named "say," an <em>inner</em> function also named "say," and a <em>static</em> method also named "say." These are three distinct methods that all exist independently of one another.
-</p>
-
+</dl><p>
+The example below shows: an <em>instance</em> method named "say," an <em>inner</em> function also named "say," and a <em>static</em> method also named "say." These are three distinct methods that all exist independently of one another.
+</p>
+
 <dl class="example">
 <dt>Use a documentation tag to describe your code.</dt>
 <dd>
@@ -223,10 +223,10 @@ <h3>Namepaths in JSDoc 3</h3>
 
 </pre>
 </dd>
-</dl><p>
-You would use three different namepath syntaxes to refer to the three different methods:
-</p>
-
+</dl><p>
+You would use three different namepath syntaxes to refer to the three different methods:
+</p>
+
 <dl class="example">
 <dt>Use a documentation tag to describe your code.</dt>
 <dd>
@@ -237,14 +237,14 @@ <h3>Namepaths in JSDoc 3</h3>
 
 </pre>
 </dd>
-</dl><p>
-You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it <em>is</em> possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.
-</p>
-
-<p>
-Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath:
-<p>
-
+</dl><p>
+You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it <em>is</em> possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.
+</p>
+
+<p>
+Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath:
+<p>
+
 <dl class="example">
 <dt>Use a documentation tag to describe your code.</dt>
 <dd>
@@ -265,11 +265,11 @@ <h3>Namepaths in JSDoc 3</h3>
 
 </pre>
 </dd>
-</dl><p>
-In this case, to refer to the method named "consider," you would use the following namepath:
-<code>Person#Idea#consider</code></p>
-
-<p>
+</dl><p>
+In this case, to refer to the method named "consider," you would use the following namepath:
+<code>Person#Idea#consider</code></p>
+
+<p>
 This chaining can be used with any combination of the connecting symbols: <code># . ~</code></p>
 
     </article>
@@ -283,3 +283,4 @@ <h3>Namepaths in JSDoc 3</h3>
 	<script>prettyPrint()</script>
 </body>
 </html>
+

about-plugins.html

@@ -838,3 +838,4 @@ <h2 name="packaging-jsdoc-3-plugins" id="packaging-jsdoc-3-plugins">
 	<script>prettyPrint()</script>
 </body>
 </html>
+