@mixin: filled out doc

Author: mathematicalcoffee

Jake/articles/tags-mixin

@@ -1,24 +1,93 @@
 <!--{
     "title":       "@mixin",
     "out":         "tags-mixin.html",
-    "description": "[todo] Document a mix-in object."
+    "description": "Document a mix-in object."
 }-->
+
+<h3>Syntax</h3>
+<code>@mixin [&lt;MixinName&gt;]</code>
+
 <h3>Overview</h3>
 
 <p>
+A mixin is a class providing functionality that is intended to be added in to other classes desiring that functionality.
+The @mixin tag allows the user to mark an object as a mixin.
+</p>
+
+<p>
+For example, you might have an "Eventful" mixin which provides event handling methods to other classes, but isn't intended to be used itself.
 </p>
 
 <h3>Examples</h3>
 
+{{#example}}Example of a @mixin
+/**
+ * This provides methods used for event handling. It's not meant to
+ * be used directly, except as a provider of related methods.
+ *
+ * @mixin
+ */
+var Eventful = {
+    /** Register a handler function to be called whenever this event is fired.
+     * @param {string} eventName - name of the event
+     * @param {Eventful~eventHandler} handler - the handler to be called.
+     */
+    on: function(eventName, handler) {
+        // code...
+    },
+   
+    /** Fires an event, causing all handlers for that event name to run.
+     * @param {string} eventName - name of the event 
+     * @param {object} eventData - passed into each handler.
+     */
+    fire: function(eventName, eventData) {
+        // code...
+    }
+};
+/** Used as an event callback {@link Eventful.on}.
+ * @callback Eventful~eventHandler
+ * @param {object} eventData - the event data.
+ */
+{{/example}}
+
 <p>
+In the above we document a set of methods, Eventful, that can be mixed in to other classes to give them the ability to fire and listen to events.
+(Note also the use of the <a href="tags-callback.html">@callback</a> tag to document the event handler parameter in the "on" function - we could have just written "@param {function(object)} handler" instead if we didn't want to use that).
 </p>
 
-{{#example}}Example goes here
-// todo
+<p>
+Use <a href="tags-mixes.html">@mixes</a> to indicate in the documentation that another class mixes in Eventful (you are still responsible for doing the actual mixing in the code, however). Note, this doesn't support references like "{@link FormButton#on}" (yet). 
+</p>
+
+{{#example}}Having another class @mixes Eventful
+/**
+ * @constructor FormButton
+ * @mixes Eventful
+ */
+var FormButton = function() {
+    // code...
+};
+FormButton.prototype.press = function() {
+  this.fire('press', {});
+}
+mix(Eventful).into(FormButton.prototype);
+
+function mix(source) {
+  return {into: function(target) {
+    for (var property in source) {
+      if( !(property in {}) ) {
+        target[property] = source[property]
+      }
+    }
+    return this;
+  }};
+}
 {{/example}}
 
 <h3>See Also</h3>
 
 <ul>
-    <li><a href="#">...</a></li>
-</ul>
+    <li><a href="tags-mixes.html">@mixes</a></li>
+    <li><a href="tags-borrows.html">@borrows</a></li>
+    <li><a href="tags-constructor.html">@class</a></li>
+</ul>

index.html

@@ -263,7 +263,7 @@ <h2 name="JSDoc3_Tag_Dictionary" id="JSDoc3_Tag_Dictionary">JSDoc 3 Tag Dictiona
 		<dd>When was this feature added?</dd>	<dt><a href="tags-access.html">@access</a></dt>
 		<dd>Specify the access level of this member - private, public, or protected.</dd>	<dt><a href="tags-borrows.html">@borrows</a></dt>
 		<dd>This object uses something from another object.</dd>	<dt><a href="tags-mixin.html">@mixin</a></dt>
-		<dd>[todo] Document a mix-in object.</dd>	<dt><a href="tags-see.html">@see</a></dt>
+		<dd>Document a mix-in object.</dd>	<dt><a href="tags-see.html">@see</a></dt>
 		<dd>[todo] Refer to some other documentation for more information.</dd>	<dt><a href="tags-file.html">@file</a></dt>
 		<dd>Describe a file.</dd>	<dt><a href="tags-example.html">@example</a></dt>
 		<dd>Provide an example of how to use a documented item.</dd>	<dt><a href="tags-tutorial.html">@tutorial</a></dt>

tags-mixin.html

@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
 	<meta charset="utf-8">
-	<meta name="description" content="[todo] Document a mix-in object."><title>Use JSDoc: @mixin</title>
+	<meta name="description" content="Document a mix-in object."><title>Use JSDoc: @mixin</title>
 
 	<link rel="stylesheet" href="lib/prettify.css" />
 	<script src="lib/prettify.js"></script>
@@ -176,29 +176,103 @@
 	<article>
 	<h1>@mixin</h1>
 
+
+<h3>Syntax</h3>
+<code>@mixin [&lt;MixinName&gt;]</code>
+
 <h3>Overview</h3>
 
 <p>
+A mixin is a class providing functionality that is intended to be added in to other classes desiring that functionality.
+The @mixin tag allows the user to mark an object as a mixin.
+</p>
+
+<p>
+For example, you might have an "Eventful" mixin which provides event handling methods to other classes, but isn't intended to be used itself.
 </p>
 
 <h3>Examples</h3>
 
+<dl class="example">
+<dt>Example of a @mixin</dt>
+<dd>
+<pre class="prettyprint lang-js">
+/**
+ * This provides methods used for event handling. It's not meant to
+ * be used directly, except as a provider of related methods.
+ *
+ * @mixin
+ */
+var Eventful = {
+    /** Register a handler function to be called whenever this event is fired.
+     * @param {string} eventName - name of the event
+     * @param {Eventful~eventHandler} handler - the handler to be called.
+     */
+    on: function(eventName, handler) {
+        // code...
+    },
+   
+    /** Fires an event, causing all handlers for that event name to run.
+     * @param {string} eventName - name of the event 
+     * @param {object} eventData - passed into each handler.
+     */
+    fire: function(eventName, eventData) {
+        // code...
+    }
+};
+/** Used as an event callback {@link Eventful.on}.
+ * @callback Eventful~eventHandler
+ * @param {object} eventData - the event data.
+ */
+
+</pre>
+</dd>
+</dl><p>
+In the above we document a set of methods, Eventful, that can be mixed in to other classes to give them the ability to fire and listen to events.
+(Note also the use of the <a href="tags-callback.html">@callback</a> tag to document the event handler parameter in the "on" function - we could have just written "@param {function(object)} handler" instead if we didn't want to use that).
+</p>
+
 <p>
+Use <a href="tags-mixes.html">@mixes</a> to indicate in the documentation that another class mixes in Eventful (you are still responsible for doing the actual mixing in the code, however). Note, this doesn't support references like "{@link FormButton#on}" (yet). 
 </p>
 
 <dl class="example">
-<dt>Example goes here</dt>
+<dt>Having another class @mixes Eventful</dt>
 <dd>
 <pre class="prettyprint lang-js">
-// todo
+/**
+ * @constructor FormButton
+ * @mixes Eventful
+ */
+var FormButton = function() {
+    // code...
+};
+FormButton.prototype.press = function() {
+  this.fire('press', {});
+}
+mix(Eventful).into(FormButton.prototype);
+
+function mix(source) {
+  return {into: function(target) {
+    for (var property in source) {
+      if( !(property in {}) ) {
+        target[property] = source[property]
+      }
+    }
+    return this;
+  }};
+}
 
 </pre>
 </dd>
 </dl><h3>See Also</h3>
 
 <ul>
-    <li><a href="#">...</a></li>
-</ul>
+    <li><a href="tags-mixes.html">@mixes</a></li>
+    <li><a href="tags-borrows.html">@borrows</a></li>
+    <li><a href="tags-constructor.html">@class</a></li>
+</ul>
+
     </article>
 
     <footer>