documon

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>Quick Reference</title> <meta name="description" content="more.quick_reference">  <link rel="stylesheet" href="assets/vendor/normalize.css">  <link rel="stylesheet" href="assets/vendor/prettify/codamike.css"> <script src="assets/vendor/prettify/prettify.js"></script>  <script> var pageCtx = { id : "more.quick_reference", name: "Quick Reference" } </script>  <link rel="stylesheet" href="assets/css/pages.css"> <script src="assets/js/documon/Storage.js"></script> <script src="assets/js/documon/Access.js"></script> <script src="assets/js/documon/Pages.js"></script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-106684927-1', 'auto'); ga('send', 'pageview'); </script> </head> <body> <div class="page"> <div class="more"><h1 id="quick-refernce">Quick Refernce</h1> <h2 id="defining-properties">Defining Properties</h2> <p>You can be robust</p> <pre><code>/** * The width of the display object's bounding box. * @property width * @type Number * @default 0 **/ p.width = 0;</code></pre> <p>Or semi-robust</p> <pre><code>/** * The width of the display object's bounding box. * @property width=0 * @type Number **/ p.width = 0;</code></pre> <p>Or one-liner #1 - name after {type}</p> <pre><code>/** * @property {object} width=0 The width of the display object's bounding box. */ p.width = 0;</code></pre> <p>Or one-liner #2 - name before {type} (unconventional, but seems more logical to me?)</p> <pre><code>/** * @property width=0 {object} The width of the display object's bounding box. */ p.width = 0;</code></pre> <h2 id="tags">Tags</h2> <p>The following flags are processed:</p> <dl> <dt>@property, @method, @event</dt> <dd><p>The three basic kinds of entities normally found in a class or module. Example: <code>@property {type} name - description</code></p></dd> <dt>@package, @namespace</dt> <dd><p>Generally only one per page, but can have to. See the "Package / Namespace" section below. Example: <code>@package foo.bar</code></p></dd> <dt>@class, @module</dt> <dd><p>Both entities are treated equally, but appear in the final rendered docs as "class". Example: <code>@class name</code></p></dd> <dt>@private, @protected, @static, @public, @readonly</dt> <dd><p>Items with these flags can be shown/hidden/filtered. Example <code>@private</code></p></dd> <dt>@overrides, @impliments, @extends, @inherits</dt> <dd><p>These items page HTML will incorporate inherited parent properties, methods and events, which can be toggled.</p></dd> <dt>@requires</dt> <dd><p>Incorporates a list of dependancies that a module or class needs to run. Generally shows up in the "meta" section. Example <code>@requires package.Class</code></p></dd> <dt>@constructor</dt> <dd><p>Generally used in conjunction with a class/module, and places a colored tag near the definition.</p></dd> <dt>@example</dt> <dd><p>Multiple examples can exist per item. A nice to have for templating, so the examples can be moved around and they don't have to be hard-coded into the main description. See the "Examples" section below.</p></dd> <dt>@param</dt> <dd><p>Classes, modules and methods can have multiple params. See "Params" section below.</p></dd> <dt>@return, @returns</dt> <dd><p>Can incorporate a {type}. Example <code>@return {object}</code></p></dd> <dt>@type</dt> <dd><p>See "Type" section below</p></dd> <dt>@order</dt> <dd><p>By default, everything is sorted alphabetically. Use this flag if you need things to appear in a specific order. Example: <code>@order 10.4</code></p></dd> <dt>@header</dt> <dd><p>Used to push a general informational entry to the top of a list. See the "Header" section below.</p></dd> <dt>@defaultVal, @default (not fully tested, since the @param approach is better)</dt> <dd><p>Used for a method's paramter that has a default value.</p></dd> <dt>@see</dt> <dd><p>Use this to link to similar or related things. See "See Also" below.</p></dd> </dl> <hr /> <h2 id="header">Header</h2> <p>A header flag provides a means to place an informational entry at the top of a main section. For example if you want an entry at the top of the Events section that provides a general overview of how the event system operates, create a new comment as follows:</p> <pre><code> /** * * The event system is really cool, I know you'll love it! * * @event * @header About Events */</code></pre> <p>It's kind of a hacky, but the <a href="https://github.com/event">@event</a> flag tells use that this header is for the events section, and the <a href="https://github.com/header">@header</a> "name" is used as the title for the section in the menu and on the page.</p> <p>Also note that internally, we use the <a href="https://github.com/order">@order</a> flag to yank this to the top of the list (so it appears first).</p> <h2 id="types">Types</h2> <p>Types are wrapped in brackets and indicate what kind of data is represented, usually:</p> <ul> <li>string</li> <li>object</li> <li>number</li> <li>boolean</li> <li>whatever you want </li> </ul> <p>Types are placed before the name</p> <pre><code>@prop {object} foo - description // yeilds type as a string: "object"</code></pre> <p>Delimit with a pipe to offer multiple types</p> <pre><code>@prop {string | object} foo - description // yields an array as ["string", "object"]</code></pre> <p>Example of indicating this property holds a DOM Element</p> <pre><code>@prop {DOM Element} foo - description // yields type as a string: "Dom Element"</code></pre> <hr /> <h2 id="default-values">Default Values</h2> <p>To define default values for properties or method parameters, use the equal sign after the name.</p> <pre><code> @prop {object} foo="bar"</code></pre> <p>You can also use the <a href="https://github.com/default">@default</a> or <a href="https://github.com/defaultVal">@defaultVal</a> flags:</p> <pre><code> @default bar @defaultVal bar</code></pre> <h2 id="optional">Optional</h2> <p>To define properties or method parameters as optional, wrap the name with quare brackets.</p> <pre><code>@prop {object} [foo]</code></pre> <p>When the property has a default value, keep the value within the square brackets as well</p> <pre><code>@prop {object} [foo="bar"]</code></pre> <h2 id="package--namespace">Package / Namespace</h2> <p>There is a commonality between the ideas of namespace and package -- each group code together into a general theme.</p> <p>Hence <a href="https://github.com/namespace">@namespace</a> and <a href="https://github.com/package">@package</a> are interchangable and hold the same meaning in Documon.</p> <p>Can be a stand alone comment or integrated into either the module or class comment:</p> <pre><code>/** * @namespace foo */ /** * My cool class * @class Cool * @namespace window */ /** * My cool module * @class Cool * @namespace path.to.access */</code></pre> <p>You are free to use whichever term suits you, but in the documentation (and in our code), we use the term "package" exclusively to addresses both concepts.</p> <p>The following will be treated exactly the same as above:</p> <pre><code>/** * @package foo */ /** * My cool class * @module Cool * @package window */ /** * My cool module * @module Cool * @package path.to.access */</code></pre> <p>We split source files whenever <a href="https://github.com/package">@package</a> or <a href="https://github.com/namespace">@namespace</a> appears -- causing the source file to be treated as multiple source files.</p> <p>This allows you to define multiple packages within a single file -- without having to incorporate the <a href="https://github.com/package">@package</a> flag into each class, method, property or event definition.</p> <p>A simple trick is to use a stand-alone comment at the top of your file:</p> <pre><code>/** * @package foo.bar */</code></pre> <p>Then further down the same file, you could include another <a href="https://github.com/package">@package</a> definition…</p> <pre><code>/** * @package bob.sally */</code></pre> <p>… or incorporate a package into a class (or any other) definition:</p> <pre><code>/** * @class sally * @package foo.bar */</code></pre> <p>… and all the classes / methods / events / properties between these <a href="https://github.com/package">@package</a> entries will be grouped together under each <a href="https://github.com/package">@package</a> "section".</p> <p>Just be aware that if put <a href="https://github.com/package">@package</a> definitions all over the place, you could get lost real fast. Use <a href="https://github.com/package">@package</a> and <a href="https://github.com/namespace">@namespace</a> sparingly.</p> <p>FYI: "package" is more common across programming languages. The idea being that a larger framework or application has files lumped together that all support a common theme. Traditionally classes that are related to the theme all reside in the same folder and the folder name describes the "theme". Thus, the folder acts as a "package" for a group of common classes. These "package" folders are further organized heirarchically within the overall framework or applicaiton structure.</p> <pre><code>app app.display app.display.bitmap app.display.vector app.db app.db.models app.db.models.sql app.db.models.json app.media app.media.audio app.media.audio.player app.media.audio.codecs</code></pre> <h2 id="examples">examples</h2> <p>Add code and text to <a href="https://github.com/example">@example</a> tags like normal with indentation or back ticks.</p> <p>IMPORTANT: For indented examples, LEAVE AN EMTPY LINE BEFORE AND AFTER !!!.</p> <pre><code> /** * @example This is text above the example * * var foo = "bar"; * * And this is text below the example */ /** * @example `var foo="bar"` */</code></pre> <p>To set the code language used to for "pretty" printing, use the {type} field. Generally, use the extension of your code files e.g. js, cpp, m.</p> <pre><code> /** * @example {js} - This is causing the following code to be rendered as javascript because the {type} is set to {js}. * * var foo = "bar"; * */</code></pre> <p>Types can be:</p> <blockquote> <p>bsh, c, cc, cpp, cs, csh, cyc, cv, htm, html, java, js, m, mxml, perl, pl, pm, py, rb, sh, xhtml, xml, xsl, apollo, basic, clj, css, dart, erlang, go, hs, lasso, lisp, llvm, logtalk, lua, matlab, ml, mumps, n, pascal, proto, r, rd, rust, scala, sql, swift, tcl, tex, vb, vhdl, wiki, xq, yaml</p> </blockquote> <p>When using the <a href="https://github.com/example">@example</a> flag, markdown is not used, and the code is taken "as is" giving you a little more control over indentaion.</p> <h2 id="links">links</h2> <p>Use markdown notation:<br /> This is and example sentance and <a href="http://www.example.com">my link</a> is all i have to say.</p> <p>For cross linking to other parts of docs:</p> <blockquote> <p>To link to another class, use the full path:</p> <pre><code> [see Foo](package.Class.method)</code></pre> <p>To link to an internal method/property just use the method/property name:</p> <pre><code> [see setWidth](setWidth)</code></pre> <p>To link to an anchor, use the traditional #</p> </blockquote> <h2 id="see-also-tags">See Also Tags</h2> <p>Use markdown link notation:</p> <pre><code> @see [describe the link here](http://www.example.com) @see [describe the link here](#package.path.Foo.setWidth) @see [describe the link here](#setWidth)</code></pre> <h2 id="inheritance">Inheritance</h2> <p>When defining <a href="https://github.com/extends">@extends</a>, you can use a short-hand for classes in the same package.</p> <p>For example, lets say we have 2 classes as:</p> <pre><code> /some/long/winded/package/Foo.js some/long/winded/package/Bar.js</code></pre> <p>… and "Bar" extends "Foo"… Rather than writing:</p> <pre><code> @class Bar @pacakge long.winded.package @extends long.winded.package.Foo</code></pre> <p>… we can write:</p> <pre><code> @class Bar @pacakge long.winded.package @extends Foo</code></pre> <p>… because Foo and Bar are in the same package. We only need to use the long-form when referencing things outside of the same package.</p> <h2 id="comments-in-comments">Comments in comments</h2> <p>If you need to include /* style comments in your comments, HTML-entity-ize the slash:</p> <pre><code> * &#47;** * * Something for B * * @method something * *&#47;</code></pre></div> </div> <div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div> </body> </html>