documon

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>Overview</title> <meta name="description" content="more.comment_authoring_guide.overview">  <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.comment_authoring_guide.overview", name: "Overview" } </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="writing-comments-overview">Writing Comments Overview</h1> <p>Documon reads <a href="https://en.wikipedia.org/wiki/Javadoc">JavaDoc</a> style blocks, which take the form of:</p> <pre><code>/** * This is the traditional code-comment style * block, with stars along the left edge. * And this comment block is positioned * immeditely above the method or property. * * @method myMethod * @param {type} arg description */ function myMethod(arg){ var foo; }</code></pre> <p>Where /** is used as a flag to designate the start of a documentation comment. </p> <blockquote> <p>NOTE: You can designate a different "start" and "end" string if your language uses non-C-like commenting. See the <a href="more.options">"docBegin/End" options</a>.</p> </blockquote> <p>With Documon, you're not required to put stars down the left-hand side, you can do somehting like this:</p> <pre><code>/** This is perfectly fine with Documon For long, complicated comments with HTML and examples may be a liitle easier to write/read. Or if it's just your preference @method myMethod @param {type} arg description */ function myMethod(arg){ var foo; }</code></pre> <h3 id="blocks">Blocks</h3> <p>A single comment block is defined for each:</p> <ul> <li>variable</li> <li>function</li> <li>event</li> <li>class</li> </ul> <p>The block contains a general top area where the <strong>long description</strong> is written. THe long description is not required.</p> <p>Tags appear after the long description. Tags are used to name, classify, categorize, link and generally describe the entity.</p> <p>Tags can consume mulitple lines.</p> <h3 id="be-robust">Be Robust</h3> <p>Documon doesn't read or interpret your source code, and relies soley on <a href="https://github.com/tags">@tags</a> within comments, hence, one of the following tags MUST exist within each code block:</p> <ul> <li><a href="https://github.com/package">@package</a> / <a href="https://github.com/namespace">@namespace</a></li> <li><a href="https://github.com/class">@class</a> / <a href="https://github.com/module">@module</a></li> <li><a href="https://github.com/method">@method</a></li> <li><a href="https://github.com/property">@property</a></li> <li><a href="https://github.com/event">@event</a></li> </ul> <p>The tags listed above are essential for Documon to construct the documentation website.</p> <h3 id="example-property">Example Property</h3> <pre><code>/** This is an example @property foo @type string */ var foo</code></pre> <p>or Documon's quick prop:</p> <pre><code>/** @property {string} foo - description */ var foo</code></pre> <h3 id="example-method">Example method</h3> <pre><code>/** This function does something @method foo @param {type} bar - description @return {type} description */ function foo(bar){ return bar + "hello"; }</code></pre> <h3 id="example-class">Example class</h3> <pre><code>/** This class does something @class foo */ function foo(bar){ return bar + "hello"; }</code></pre></div> </div> <div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div> </body> </html>