Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
2313 lines (1401 sloc) 62.6 KB
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>coddoc</title>
<link rel="stylesheet" href="http://twitter.github.com/bootstrap/assets/css/bootstrap.css">
<link rel="stylesheet" href="http://twitter.github.com/bootstrap/assets/css/bootstrap-responsive.css">
<link rel="stylesheet" href="http://twitter.github.com/bootstrap/assets/js/google-code-prettify/prettify.css">
<style type="text/css">
.subnav-inner {
width: 100%;
height: 36px;
background-color: #EEE;
background-repeat: repeat-x;
background-image: -moz-linear-gradient(top, whiteSmoke 0%, #EEE 100%);
background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, whiteSmoke), color-stop(100%, #EEE));
background-image: -webkit-linear-gradient(top, whiteSmoke 0%, #EEE 100%);
background-image: -ms-linear-gradient(top, whiteSmoke 0%, #EEE 100%);
background-image: -o-linear-gradient(top, whiteSmoke 0%, #EEE 100%);
filter: progid:DXImageTransform.Microsoft.gradient(startColorstr = '#f5f5f5', endColorstr = '#eeeeee', GradientType = 0);
background-image: linear-gradient(top, whiteSmoke 0%, #EEE 100%);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}
.subnav .nav > li > a:hover {
color: black !important;
}
.subnav .nav li.dropdown .dropdown-toggle .caret,
.subnav .nav li.dropdown.open .caret {
border-top-color: #999 !important;
border-bottom-color: #999 !important;
}
.subnav-fixed {
position: fixed;
width : 90%;
margin-right: auto;
margin-left: auto;
top: 40px;
left: 0;
right: 0;
z-index: 1020;
border-color: #D5D5D5;
border-width: 0 0 1px;
-webkit-border-radius: 0;
-moz-border-radius: 0;
border-radius: 0;
-webkit-box-shadow: inset 0 1px 0 #fff, 0 1px 5px rgba(0,0,0,.1);
-moz-box-shadow: inset 0 1px 0 #fff, 0 1px 5px rgba(0,0,0,.1);
box-shadow: inset 0 1px 0 #fff, 0 1px 5px rgba(0,0,0,.1);
filter: progid:DXImageTransform.Microsoft.gradient(enabled=false);
}
.navbar .nav .dropdown-menu {
max-height: 500px;
overflow: auto;
}​
</style>
<style type="text/css">
body {
padding-top: 60px;
padding-bottom: 40px;
}
</style>
<script type="text/javascript">
var init = (function () {
"use strict";
var processScroll = (function () {
var curr = null, prev = null;
return function (nav) {
var $win = $(window);
$('.subnav').each(function () {
var nav = $(this);
var navTop = nav.offset().top - 40;
var scrollTop = $win.scrollTop();
if (scrollTop >= navTop && curr != nav) {
if(curr){
curr.removeClass('subnav-fixed')
prev = curr;
}
curr = nav;
curr.addClass('subnav-fixed')
} else if (curr == nav && scrollTop <= navTop) {
curr.removeClass('subnav-fixed');
prev.addClass('subnav-fixed');
curr = prev;
}else{
nav.removeClass('subnav-fixed');
}
});
};
})();
return function () {
window.prettyPrint && prettyPrint();
$(".collapse").collapse();
// fix sub nav on scroll
processScroll();
$(window).on('scroll', processScroll)
}
})();
</script>
</head>
<body onload="init()">
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a href="./index.html" class="brand">coddoc</a>
<div class="nav-collapse">
<ul class="nav nav-pills">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#coddoc">coddoc</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#coddoc_Context">coddoc.Context</a></li>
<li><a href="#coddoc_Symbol">coddoc.Symbol</a></li>
<li><a href="#coddoc_Tree">coddoc.Tree</a></li>
</ul>
</li>
</ul>
<ul class="nav pull-right">
<li><a href="https://github.com/doug-martin/coddoc" target="#github" class="pull-right">github</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="container-fluid">
<a name="top"></a>
<div class="container">
<h1>Coddoc</h1>
<h2> Description</h2>
<p>
coddoc is a jsdoc parsing library. Coddoc is different in that it is easily extensible by allowing users to
add tag and code parsers through the use of <a href='#coddoc_addTagHandler'> coddoc.addTagHandler</a> and <a href='#coddoc_addCodeHandler'> coddoc.addCodeHandler</a>.
coddoc also parses source code to be used in APIs.
</p>
<p>
Coddoc also supports the generation of markdown and html through the use of different templates. Currently
the templates use <a href="http://handlebarsjs.com/">Handlebars</a> but you may use any templating engine
you wish
</p>
<h3>JSDOC Tags</h3>
<p>
JSDoc tags currently supported are:
<ul>
<li>augments|extends : extend an object</li>
<li>lends : document all members of an anonymous object as members of a declared symbol</li>
<li>namespace : document a namespace</li>
<li>parameter|param|arg|argument : parameters of a function</li>
<li>return|returns : return value of a function</li>
<li>memberof|memberOf : explicitly document a cod block as a member of an object</li>
<li>name : explicitly document the name of a symbol</li>
<li>constructor|constructs : document a symbol as a constructor for a class</li>
<li>class : documents a symbol as a class</li>
<li>classdesc : alternate way to add a description to a class</li>
<li>example : document an example/s of a symbol</li>
<li>private : document a symbol as private.</li>
<li>ignore : allows you to document a symbol but ignore it in parsing</li>
<li>method|function : explicily document a symbol as a method</li>
<li>field : explicily document a symbol as a field</li>
<li>type : document the type of a field</li>
<li>default : document the default value of a field</li>
<li>throws|throw|exception : document any exception thrown by a method</li>
<li>property : document a property in the constructor declaration of a class</li>
<li>borrows : document any filed/methods borrowed from a class</li>
<li>constant|const : document a field as a constant</li>
<li>desc|description : alternate way to explicitly document the description of a symbol</li>
<li>public:explicitly document a symbol as public</li>
</ul>
<h3>Coddoc Tags</h3>
Coddoc also has a few additional tags.
<ul>
<li>ignoreCode : ignore the parsed code in the output</li>
<li>includeDoc : include an external doc. External docs can be html or markdown.
Example <pre class='prettyprint linenums lang-js'>
&#64;includeDoc [Title Of Doc] ../location/of_doc.md
</pre>
</li>
<li>projectName : document the projectName</li>
<li>github : url to github project</li>
<li>code : specifies a code block without needing an <code>example</code> tag
Example <pre class='prettyprint linenums lang-js'>
&#123;&#64;code var test = "test"; &#125;
</pre>
</li>
<li>header : allows you to document a header that should appear before
generated documentation</li>
<li>footer : allows you to document a footer that should come after the generated documentation</li>
<li>protected : allows you to document a field as protected</li>
</ul>
</p>
<h2>Installation</h2>
Locally
<pre class='prettyprint linenums lang-js'>
npm install coddoc
</pre>
Globally
<pre class='prettyprint linenums lang-js'>
npm install -g coddoc
</pre>
<h2>Usage</h2>
Down doc does not currently create multi file docs instead will output to a single file. You may however implement
your own formatter to create multiple files.
Command line options
<ul>
<li>-d --directory : the directory that contains your code</li>
<li>[-f --formatter] : optional formatter to use, if not specified then a JSON object of the symbols will
be output</li>
<li>[-p --pattern] : optional file pattern to use when searching for files</li>
</ul>
Examples
JSON output
<pre class='prettyprint linenums lang-js'>
coddoc -d ./lib > symbols.json
</pre>
To use the markdown formatter
<pre class='prettyprint linenums lang-js'>
coddoc -d ./lib -f markdown > README.md
</pre>
To use the HTML formatter
<pre class='prettyprint linenums lang-js'>
coddoc -d ./lib -f html > index.html
</pre>
To use pragmatically
<pre class='prettyprint linenums lang-js'>
var coddoc = require("coddoc");
var tree = coddoc.parse({directory : __dirname + "/lib"});
var classes = tree.classes, namespaces = tree.namespaces;
//do something
</pre>
<h2>API</h2>
<a name="coddoc"></a>
<div class="navbar subnav">
<div class="navbar-inner subnav-inner">
<div class="container">
<a href="#" class="brand">
coddoc
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<div class="nav-collapse">
<ul class="nav pull-right">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Methods<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#coddoc_addCodeHandler">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-success">P</span>
addCodeHandler
</a></li>
<li><a href="#coddoc_addTagHandler">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-success">P</span>
addTagHandler
</a></li>
<li><a href="#coddoc_getTagRegexp">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-warning">P</span>
getTagRegexp
</a></li>
<li><a href="#coddoc_parse">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-warning">P</span>
parse
</a></li>
<li><a href="#coddoc_parseCode">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-warning">P</span>
parseCode
</a></li>
<li><a href="#coddoc_parseTag">
<span class="label label-info">S</span>
<span class="label label-label">F</span>
<span class="label label-warning">P</span>
parseTag
</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
<em>Defined index.js</em>
<p>
Entry point for parsing code.</p>
<em>Example</em>
<pre class="prettyprint linenums lang-js">
var tree = coddoc({directory : path.resolve(__dirname + &quot;lib&quot;)});
//To use markdown formatter
var doc = coddoc({directory : path.resolve(__dirname + &quot;lib&quot;), formatter : coddoc.formatters.markdown});
//To use html formatter
var doc = coddoc({directory : path.resolve(__dirname + &quot;lib&quot;), formatter : coddoc.formatters.html});
//To use custom file pattern
var doc = coddoc({directory : path.resolve(__dirname + &quot;lib&quot;), patter : /.+\.test\.js$/i, formatter : coddoc.html});
</pre>
<em>Arguments</em>
<ul>
<li> <em>options</em> : options object.</li>
<li> <em>options.dir</em> <code>String</code> : the directory of code to parse.</li>
<li> <em>[options.pattern= <code>/.+\.js$/i</code>]</em> <code>RegExp</code> : a regular expression to test files agains</li>
<li> <em>options.formatter?</em> <code>Object</code> : And optional formatter to format the tree. The object must contain
a <code>generate</code> method. See <a href='#coddoc_formatters_html'> coddoc.formatters.html</a></li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (options){
options = options || {};
var baseDir = options.dir, filePattern = options.pattern || FILE_PATTERN;
if (!baseDir) {
console.log(&quot;directory required&quot;);
}
var fileMap = {};
(function findFiles(dir) {
var files = fs.readdirSync(dir);
files.forEach(function (file) {
var filePath = path.resolve(dir, file);
var stat = fs.statSync(filePath);
if (stat.isDirectory()) {
findFiles(filePath);
} else if (stat.isFile() &amp;&amp; filePattern.test(file)) {
fileMap[filePath] = fs.readFileSync(filePath, &quot;utf8&quot;);
}
});
}(baseDir));
var context = new Context(), tree = new Tree();
Object.keys(fileMap).forEach(function (i, j) {
emitter.emit(&quot;file&quot;, i);
context.activateScope(&quot;global&quot;);
parser.parse(fileMap[i], path.relative(baseDir, i), tree, context, emitter);
});
return tree;
}
</pre>
<a name="coddoc_addCodeHandler"></a>
<h3>
addCodeHandler
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined parser/code.js</em>
<p>
Adds a handler for a particular code regular expression. Useful if you want to
match a specific type of code not handled by default. When inside of of the parse function
you can use the <code>RegExp.$</code> properties to access match sub expressions.
By Default code blocks of the following form are parsed.
<pre>
// /^function (\w+) *\{/
function(){}
// /^var *(\w+) *= *function/
var x = function(){};
// /^(\w+(?:\.\w+)*)\.prototype\.(\w+(?:\.\w+)?) *= *function/
MyObject.prototype.testFunction = function(){};
// /^(\w+(?:\.\w+)*)\.prototype\.(\w+(?:\.\w+)?) *= *([^\n;]+)/
MyObject.prototype.testProperty = "property";
// /^(\w+(?:\.\w+)+) *= *function/
some.object.testFunction = function(){}
// /^(\w+(?:\.\w+)+) *= *([^\n;]+)/
some.object.testFunction = ["some", "property"];
// /^var +(\w+) *= *([^\n;]+)/
var testProperty = {my : "property"};
var myObject = {
// /^\"?(\w+)\"? *\: *function/
testFunction : function(){},
// /^\"?(\w+)\"? *\: *([^,\n]+)/
testProperty : "some property"
}
</pre>
</p>
<em>Example</em>
<pre class="prettyprint linenums lang-js">
var util = require(&quot;coddoc&quot;).util;
//parse code in the format of var myLocal = name.space.myFunction = function(){};
//give it a high priority to allow it to override current handlers.
addHandler(/^var *\w+ *= * (\w+(?:\.\w+)*) = *function/, 20, function (str, symbol, context) {
var splitName = util.splitName(RegExp.$1), name = splitName.name, activeScope = splitName.memberof, params = util.getParamList(str);
return {
type:&#x27;function&#x27;,
isFunction:true,
memberof:activeScope,
isStatic:activeScope ? !activeScope.match(&quot;.prototype&quot;) : false,
isPrivate:name.match(/^_/) != null,
name:name,
params:params,
code:[&#x27;function (&#x27;, params.map(
function (n) {
return n.name.name;
}).join(&quot;,&quot;), &#x27;){\n &#x27;, util.getCode(str, &quot;{&quot;).split(&quot;\n&quot;).join(&quot;\n &quot;), &quot;\n}&quot;].join(&quot;&quot;)
};
});
</pre>
<em>Arguments</em>
<ul>
<li> <em>regexp</em> : the regular expression used to match code blocks.</li>
<li> <em>[priority= <code>0</code>]</em> : the priority to give this code handler if not provided
it is defaulted to 0.</li>
<li> <em>parse</em> : a function that returns an object. The object will be set as the <code>codeObject</code> on the <a href='#coddoc_Symbol'> coddoc.Symbol</a>. The properties of the object will be added to the <a href='#coddoc_Symbol'> coddoc.Symbol</a> for processing later.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (regexp,priority,parse){
if (util.isFunction(priority)) {
parse = priority;
priority = 0;
}
handlers.push({
priority:priority,
match:function (str) {
return regexp.exec(str);
},
parse:parse
});
handlers.sort(sortHandlers);
}
</pre>
<a name="coddoc_addTagHandler"></a>
<h3>
addTagHandler
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined parser/tags.js</em>
<p>
Adds a new tag to be parsed. You can use this to add custom tags. <a href='#coddoc'> coddoc</a> will
not do anything with the new tag by default, however you can add functionality to handle the
new tag in the template.
</p>
<em>Example</em>
<pre class="prettyprint linenums lang-js">
//if a tag is contains a &#x27;|&#x27; character then each variation will resolve the the same parser function.
coddoc.addTagHandler(&quot;void|VOID|Void&quot;, function(comment, symbol, context){
//do something with the tag or add properties to the symbol.
symbol.isVoid = true;
symbol.tags.push({tag : &quot;void&quot;, props : {}});
});
//in the template you can add functionality to handle the new tag. For example:
//in the html symbol.tmpl you could add a new label to the name header
&lt;h3&gt;
{{name}}
{{#if isStatic}}
&lt;span class=&quot;label label-info&quot;&gt;Static&lt;/span&gt;
{{/if}}
{{#if isFunction}}
&lt;span class=&quot;label label-label&quot;&gt;Function&lt;/span&gt;
{{/if}}
{{#if isPrivate}}
&lt;span class=&quot;label label-important&quot;&gt;Private&lt;/span&gt;
{{else}}
{{#if isProtected}}
&lt;span class=&quot;label label-warning&quot;&gt;Protected&lt;/span&gt;
{{else}}
&lt;span class=&quot;label label-success&quot;&gt;Public&lt;/span&gt;
{{/if}}
{{/if}}
{{#if isVoid}}
&lt;span class=&quot;label label-label&quot;&gt;Void&lt;/span&gt;
{{/if}}
&lt;/h3&gt;
</pre>
<em>Arguments</em>
<ul>
<li> <em>tag</em> : the tag to parse, if a tag is contains a '|' character then the string will be split and each variation will resolve to the same parse function. If the tag already exists then the old implementation will be replaced by the new one.</li>
<li> <em>parse</em> : a parser function to invoke when a tag that matches the name is encountered.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (tag,parse){
tag.split(&quot;|&quot;).forEach(function (tag) {
tags[tag] = {
parse:parse || function () {
return {tag:tag, props:{}};
}};
});
}
</pre>
<a name="coddoc_getTagRegexp"></a>
<h3>
getTagRegexp
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-warning">Protected</span>
</h3>
<hr/>
<em>Defined parser/tags.js</em>
<p>
Returns a regular expression that can be used to parse tags
</p>
<em>Returns</em>
<ul>
<li> <code>RegExp</code> a regular expression to parse valid tags.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
return new RegExp(&quot;@(&quot; + Object.keys(tags).join(&quot;|&quot;) + &quot;)&quot;);
}
</pre>
<a name="coddoc_parse"></a>
<h3>
parse
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-warning">Protected</span>
</h3>
<hr/>
<em>Defined parser/index.js</em>
<p>
Parses a string of code into <a href='#coddoc_Symbol'> coddoc.Symbol</a>s. All processed symbols are added to the <a href='#coddoc_Tree'> coddoc.Tree</a>.
This method is not intended to be used directly by user code.
</p>
<em>Arguments</em>
<ul>
<li> <em>str</em> : the source code to parse</li>
<li> <em>filepath</em> : the relative filepath where the source is located. This is set on the symbol during parsing.</li>
<li> <em>tree</em> : the tree which contains all symbols.</li>
<li> <em>context</em> : the context which holds information about the current parsing job.</li>
<li> <em>emitter</em> : </li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> </li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (str,filepath,tree,context,emitter){
var l = str.length;
var symbols = [];
for (var i = 0; i &lt; l; i++) {
var tags = [];
var comment = &quot;&quot;, c = str[i], startIndex = i, endIndex, ret = [];
var startCIndex = str.indexOf(&quot;/**&quot;, i);
if (startCIndex !== -1) {
i = startCIndex + 2;
var endCIndex = str.indexOf(&quot;*/&quot;, i);
if (endCIndex !== -1) {
comment = str.substr(startCIndex + 2, endCIndex - (startCIndex + 2)).split(&quot;\n&quot;).map(joinAndReplace).join(&quot;\n&quot;);
emitter.emit(&quot;comment&quot;, comment);
i = endCIndex + 1;
//console.log(str.substr(startCIndex, endCIndex - startCIndex));
//console.log(comment);
var res = parseTags({comment:comment, start:startCIndex, end:endCIndex + 2}, str, filepath, context),
sym = res.symbol;
symbols.push(sym);
emitter.emit(&quot;symbol&quot;, sym);
var memberof = sym.memberof;
if (!sym.ignore &amp;&amp; !sym.lends) {
tree.addSymbol(sym);
}
}
} else {
i++;
}
}
return {symbols:symbols, code:str};
}
</pre>
<a name="coddoc_parseCode"></a>
<h3>
parseCode
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-warning">Protected</span>
</h3>
<hr/>
<em>Defined parser/code.js</em>
<p>
Uses Registered handlers to parse the next block of code from a code fragment. This function is
used by <a href='#coddoc_parse'> coddoc.parse</a> to parse code for comments.
</p>
<em>Arguments</em>
<ul>
<li> <em>str</em> : the source string to parse</li>
<li> <em>symbol</em> : the symbol to add parsed properties from.</li>
<li> <em>context</em> : the current context</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (str,symbol,context){
var l = handlers.length, ret = {};
for (var i = 0; i &lt; l; i++) {
var h = handlers[i];
if (h.match(str)) {
ret = h.parse(str, symbol, context);
break;
}
}
if (ret) {
symbol.codeObject = ret;
Object.keys(ret).forEach(function (i) {
symbol[i] = ret[i];
});
}
}
</pre>
<a name="coddoc_parseTag"></a>
<h3>
parseTag
<span class="label label-info">Static</span>
<span class="label label-label">Function</span>
<span class="label label-warning">Protected</span>
</h3>
<hr/>
<em>Defined parser/tags.js</em>
<p>
Parses a tag and the coresponding comment using a matching tag handler. Each parsed tag
could add a new property to the <a href='#coddoc_Symbol'> coddoc.Symbol</a>. The parsed tag will be added the the
<a href='#coddoc_Symbol_prototype_tags'> coddoc.Symbol#tags</a> array.
</p>
<em>Example</em>
<pre class="prettyprint linenums lang-js">
coddoc.parseTag(&quot;someTag&quot;, &quot;@someTag props...&quot;, sym, src, index, context);
//would add a new tag to the symbols property
{
tag : &quot;tagname&quot;,
props : {...}
}
//the props value would also be added to the symbols params array.
</pre>
<em>Arguments</em>
<ul>
<li> <em>comment</em> : the comment fragment being parsed</li>
<li> <em>sym</em> : the symbol that the comment corresponds to. The code object and values will have already been set.</li>
<li> <em>context</em> : the currect context object. The context allows tags to set new scopes and namespaces.</li>
<li> <em>tag</em> <code>String</code> : the tag name being parsed from the comment</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (comment,sym,context){
var tag = comment.match(TAG_REGEXP), ret = {};
if (tag &amp;&amp; tag.length === 2) {
var t = tags[tag[1]];
if (t) {
t.parse(comment, sym, context);
} else {
throw new Error(&quot;Invalid tag &quot; + tag);
}
}
}
</pre>
<a name="coddoc_Context"></a>
<div class="navbar subnav">
<div class="navbar-inner subnav-inner">
<div class="container">
<a href="#" class="brand">
coddoc.Context
<span class="label label-success">Public</span>
</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<div class="nav-collapse">
<ul class="nav pull-right">
<li><a href="#coddoc_Context_constructor">Constructor</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Instance Methods<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#coddoc_Context_prototype_activateScope">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
activateScope
</a></li>
<li><a href="#coddoc_Context_prototype_addNamespace">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
addNamespace
</a></li>
<li><a href="#coddoc_Context_prototype_addScope">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
addScope
</a></li>
<li><a href="#coddoc_Context_prototype_getActiveScope">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getActiveScope
</a></li>
<li><a href="#coddoc_Context_prototype_getActiveScopeName">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getActiveScopeName
</a></li>
<li><a href="#coddoc_Context_prototype_getNamespace">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getNamespace
</a></li>
<li><a href="#coddoc_Context_prototype_getScope">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getScope
</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
<p>
A Context object used to keep state when parsing symbols.
The context should not be used directly by user code.
</p>
<a name="coddoc_Context_constructor"></a>
<h3>Constructor</h3>
<em>Defined context.js</em>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
this.scopes = {};
this.nameSpaces = {global:[]};
this.aliases = {};
this.activateScope(&quot;global&quot;);
}
</pre>
<a name="coddoc_Context_prototype_activateScope"></a>
<h3>
activateScope
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Activates a scope for.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the scope.</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> the activated scope object.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
this.activeScope = name;
return this.addScope(name);
}
</pre>
<a name="coddoc_Context_prototype_addNamespace"></a>
<h3>
addNamespace
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Adds a namespace the the context object.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the namespace</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> the object for the namespace.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
if (&quot;undefined&quot; === typeof this.nameSpaces[name]) {
this.nameSpaces[name] = {};
}
return this.nameSpaces[name];
}
</pre>
<a name="coddoc_Context_prototype_addScope"></a>
<h3>
addScope
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Adds a scope to the context
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the scope to add,</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> the object for the namespace.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
if (&quot;undefined&quot; === typeof this.scopes[name]) {
this.scopes[name] = {};
}
return this.scopes[name];
}
</pre>
<a name="coddoc_Context_prototype_getActiveScope"></a>
<h3>
getActiveScope
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Returns the active scope.
</p>
<em>Returns</em>
<ul>
<li> <code>Object</code> the scope object</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
return this.getScope(this.activeScope);
}
</pre>
<a name="coddoc_Context_prototype_getActiveScopeName"></a>
<h3>
getActiveScopeName
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Returns the name of the active scope.
</p>
<em>Returns</em>
<ul>
<li> <code>String</code> the active scope name.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
return this.activeScope;
}
</pre>
<a name="coddoc_Context_prototype_getNamespace"></a>
<h3>
getNamespace
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Gets a namespace, creating it if it does not exist.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the context</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> the object for the namespace.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
return this.addNamespace(name);
}
</pre>
<a name="coddoc_Context_prototype_getScope"></a>
<h3>
getScope
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined context.js</em>
<p>
Gets a scope creating it if it does not exist.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the scope to get,</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Object</code> the object for the namespace.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
return this.addScope(name);
}
</pre>
<a name="coddoc_Symbol"></a>
<div class="navbar subnav">
<div class="navbar-inner subnav-inner">
<div class="container">
<a href="#" class="brand">
coddoc.Symbol
<span class="label label-important">Private</span>
</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<div class="nav-collapse">
<ul class="nav pull-right">
<li><a href="#coddoc_Symbol_constructor">Constructor</a></li>
<li><a href="#coddoc_Symbol_instanceProperties">Instance Properties</a></li>
</ul>
</div>
</div>
</div>
</div>
<p>
A Symbol represents a comment and code pair. Each code handler added through <a href='#coddoc_addCodeHandler'> coddoc.addCodeHandler</a> and
tag handler added through <a href='#coddoc_addTagHandler'> coddoc.addTagHandler</a> adds/removes properties from a the symbol. Each symbol is
added to the <a href='#coddoc_Tree'> coddoc.Tree</a> which is either returned from <a href='#coddoc'> coddoc</a> or passed into a template handler.
<b>NOTE: This object should not be instantiated by user code</b>
</p>
<a name="coddoc_Symbol_instanceProperties"></a>
<em>Instance Properties</em>
<table class='table table-bordered table-striped'><tr><td>Property</td><td>Type</td><td>Default Value</td><td>Description</td></tr><tr><td>augments</td><td>{Array}</td><td><code>
[]
</code></td><td>
Any symbols this symbol augments
</td><tr><tr><td>borrows</td><td>{Array}</td><td><code>
[]
</code></td><td>
Any properties this symbol borrows
</td><tr><tr><td>codeObject</td><td>{Object}</td><td><code>null</code></td><td>
The codeObject of this symbol
</td><tr><tr><td>description</td><td>{String}</td><td><code>""</code></td><td>
The description of this symbol.
</td><tr><tr><td>examples</td><td>{Array}</td><td><code>
[]
</code></td><td>
The examples for this symbol
</td><tr><tr><td>file</td><td>{String}</td><td><code>""</code></td><td>
The file where the symbol was found.
</td><tr><tr><td>fullname</td><td>{String}</td><td><code>""</code></td><td>
The fullname i.e ({memberof}.{name})
</td><tr><tr><td>ignore</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if the symbol should be ignored and not put into <a href='#coddoc_Tree'> coddoc.Tree</a>
</td><tr><tr><td>ignoreCode</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if the code object from this symbol should be ignored.
</td><tr><tr><td>isConstant</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if this symbol is a constant.
</td><tr><tr><td>isConstructor</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true is this symbol is a constructor
</td><tr><tr><td>isFunction</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if this symbol is a function.
</td><tr><tr><td>isPrivate</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if this symbol is private.
</td><tr><tr><td>isProtected</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if this symbol is protected.
</td><tr><tr><td>isStatic</td><td>{Boolean}</td><td><code>false</code></td><td>
Set to true if this symbol is static
</td><tr><tr><td>memberof</td><td>{String}</td><td><code>""</code></td><td>
Who this symbol belongs to.
</td><tr><tr><td>name</td><td>{String}</td><td><code>""</code></td><td>
The name of this symbol
</td><tr><tr><td>params</td><td>{Array}</td><td><code>
[]
</code></td><td>
The associated params for this symbol if it is a funciton.
</td><tr><tr><td>properties</td><td>{Array}</td><td><code>
[]
</code></td><td>
The associated properties for this symbol
</td><tr><tr><td>returns</td><td>{Array}</td><td><code>
[]
</code></td><td>
Array of return types for this symbol
</td><tr><tr><td>see</td><td>{Array}</td><td><code>
[]
</code></td><td>
Any link for this symbol
</td><tr><tr><td>tags</td><td>{Array}</td><td><code>
[]
</code></td><td>
The associated tags for this symbol
</td><tr><tr><td>throws</td><td>{Array}</td><td><code>
[]
</code></td><td>
Exceptions thrown by this symbol
</td><tr><tr><td>type</td><td>{*}</td><td><code>null</code></td><td>
The type that is symbol represents.
</td><tr></table>
<a name="coddoc_Symbol_constructor"></a>
<h3>Constructor</h3>
<em>Defined symbol.js</em>
<em>Arguments</em>
<ul>
<li> <em>options</em> : an object or symbol whos properties will be added to this symbol. Note a deep copy of paraemeters will not be made, so if you pass an array the array will not be cloned.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (options){
this.tags = [];
this.params = [];
this.properties = [];
this.examples = [];
this.borrows = [];
this.augments = [];
this.includedDocs = [];
this.see = [];
this.throws = [];
this.returns = [];
options = options || {};
for (var i in options) {
if (i in this) {
this[i] = options[i];
}
}
}
</pre>
<a name="coddoc_Tree"></a>
<div class="navbar subnav">
<div class="navbar-inner subnav-inner">
<div class="container">
<a href="#" class="brand">
coddoc.Tree
<span class="label label-important">Private</span>
</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<div class="nav-collapse">
<ul class="nav pull-right">
<li><a href="#coddoc_Tree_constructor">Constructor</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Instance Methods<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#coddoc_Tree_prototype__addSymbol">
<span class="label label-label">F</span>
<span class="label label-important">P</span>
_addSymbol
</a></li>
<li><a href="#coddoc_Tree_prototype_addSymbol">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
addSymbol
</a></li>
<li><a href="#coddoc_Tree_prototype_getClasses">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getClasses
</a></li>
<li><a href="#coddoc_Tree_prototype_getMembers">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getMembers
</a></li>
<li><a href="#coddoc_Tree_prototype_getNamespaces">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getNamespaces
</a></li>
<li><a href="#coddoc_Tree_prototype_getSymbol">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
getSymbol
</a></li>
<li><a href="#coddoc_Tree_prototype_hasSymbol">
<span class="label label-label">F</span>
<span class="label label-success">P</span>
hasSymbol
</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
<p>
A Tree object which contains symbols.
</p>
<a name="coddoc_Tree_constructor"></a>
<h3>Constructor</h3>
<em>Defined tree.js</em>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
this.symbols = {global:[]};
}
</pre>
<a name="coddoc_Tree_prototype__addSymbol"></a>
<h3>
_addSymbol
<span class="label label-label">Function</span>
<span class="label label-important">Private</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Adds a symbol to this tree.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the symbol to add.</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Array</code> </li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
var ret = this.symbols[name];
if (!ret) {
ret = this.symbols[name] = [];
}
return ret;
}
</pre>
<a name="coddoc_Tree_prototype_addSymbol"></a>
<h3>
addSymbol
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Entry point to add the symbol
</p>
<em>Arguments</em>
<ul>
<li> <em>symbol</em> : </li>
<li> <em>path</em> <code>String</code> : the path of the symbol. i.e the memberof property of a symbol</li>
<li> <em>name</em> : </li>
<li> <em>obj</em> : </li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (symbol){
var nameParts = utils.splitName(symbol.fullName);
var path = nameParts.memberof, name = nameParts.name;
if (path === &quot;global&quot;) {
path = name;
}
var sym = this.getSymbol(path);
sym.push(symbol);
}
</pre>
<a name="coddoc_Tree_prototype_getClasses"></a>
<h3>
getClasses
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Returns all classes in the tree. The following properties are added to each class symbol.
<ul>
<li>staticMethods : all static methods for the class</li>
<li>staticProperties : all static properties for the class</li>
<li>instanceMethods : all isntance methods for the class</li>
<li>instanceProperties : all instance properties for a class</li>
</ul>
</p>
<em>Returns</em>
<ul>
<li> <code>Array</code> </li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
var symbols = this.symbols,
objects = [],
keys = Object.keys(this.symbols);
keys.forEach(function (k) {
objects = objects.concat(symbols[k].filter(function (s) {
return s.isConstructor;
}));
});
return objects.map(function (s) {
var name = s.fullName;
var statics = symbols[name] || [];
var instance = symbols[name + &quot;.prototype&quot;] || [];
var borrowedMethods = [], borrowedProperties = [], staticBorrowedMethods = [], staticBorrowedProperties = [];
s.borrows.map(function (b) {
var borrows = b.borrows;
var symbol = symbols[borrows.memberof || &quot;global&quot;].filter(function (s) {
return s.name === borrows.name;
});
if (symbol.length) {
symbol = symbol[0];
var memberof = b.isStatic ? name : name + &quot;.prototype&quot;;
var newSymb = new Symbol(utils.merge({}, symbol, {name:b.as, isStatic:b.isStatic, fullName:memberof + &quot;.&quot; + b.as, memberof:memberof}));
if (b.isStatic) {
if (s.isFunction) {
staticBorrowedMethods.push(newSymb);
} else {
staticBorrowedProperties.push(newSymb);
}
} else {
if (s.isFunction) {
borrowedMethods.push(newSymb);
} else {
borrowedProperties.push(newSymb);
}
}
}
});
s.name = name;
s.staticMethods = statics.filter(
function (s) {
return s.isFunction &amp;&amp; !s.isConstructor;
}).concat(staticBorrowedMethods);
s.staticProperties = statics.filter(
function (s) {
return !s.isFunction &amp;&amp; !s.isNamespace;
}).concat(staticBorrowedProperties);
s.instanceMethods = instance.filter(
function (s) {
return s.isFunction &amp;&amp; !s.isConstructor;
}).concat(borrowedMethods);
s.instanceProperties = instance.filter(
function (s) {
return !s.isFunction &amp;&amp; !s.isNamespace;
}).concat(s.properties || []).concat(borrowedProperties);
return s;
});
}
</pre>
<a name="coddoc_Tree_prototype_getMembers"></a>
<h3>
getMembers
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Gets all members(<a href='#coddoc_Symbol'> coddoc.Symbol</a>) for a particular path.
</p>
<em>Arguments</em>
<ul>
<li> <em>path</em> : the path to look up.</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Array</code> and array of symbols.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (path){
var symbols = this.symbols,
namespaces = [],
keys = Object.keys(this.symbols);
keys.forEach(function (k) {
namespaces = namespaces.concat(symbols[k].filter(function (s) {
return !s.isNamespace &amp;&amp; !s.isConstructor &amp;&amp; s.memberof === path;
}));
});
return namespaces;
}
</pre>
<a name="coddoc_Tree_prototype_getNamespaces"></a>
<h3>
getNamespaces
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Returns all namespaces in this tree. This method also adds the following values to the namespace.
<ul>
<li>properties : all properties that belong to the namespace</li>
<li>methods : all methods that belong to the namespace</li>
</ul>
</p>
<em>Returns</em>
<ul>
<li> <code>Array</code> array of namespaces</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (){
var symbols = this.symbols,
namespaces = [],
keys = Object.keys(this.symbols);
keys.forEach(function (k) {
namespaces = namespaces.concat(symbols[k].filter(function (s) {
return s.isNamespace;
}));
});
return namespaces.map(function (s) {
var realName = s.memberof &amp;&amp; s.memberof !== &quot;global&quot; ? [s.memberof, s.name].join(&quot;.&quot;) : s.name;
var members = this.getMembers(realName);
s.name = realName;
s.properties = s.properties.concat(members.filter(function (m) {
return !m.isFunction;
}));
s.methods = members.filter(function (m) {
return m.isFunction;
});
return s;
}, this);
}
</pre>
<a name="coddoc_Tree_prototype_getSymbol"></a>
<h3>
getSymbol
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Returns a symbol from this tree. The Tree will create the symbol if it does not exist.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name of the symbol to get</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Array</code> the array for the symbol.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
return this._addSymbol(name);
}
</pre>
<a name="coddoc_Tree_prototype_hasSymbol"></a>
<h3>
hasSymbol
<span class="label label-label">Function</span>
<span class="label label-success">Public</span>
</h3>
<hr/>
<em>Defined tree.js</em>
<p>
Returns true if this tree contains a symbol.
</p>
<em>Arguments</em>
<ul>
<li> <em>name</em> : the name to test if the tree contains the symbol</li>
</ul>
<em>Returns</em>
<ul>
<li> <code>Boolean</code> true if the tree contains the symbol.</li>
</ul>
<em>Source</em>
<pre class="prettyprint linenums lang-js">
function (name){
var parts = name.split(&quot;.&quot;);
return !!this.symbols[name];
}
</pre>
<h2>License</h2>
<p>MIT <a href = https://github.com/Pollenware/coddoc/raw/master/LICENSE>LICENSE</a><p>
<h2>Meta</h2>
<hr>
<p>Code: <code>git clone git://github.com/pollenware/coddoc.git</code></br></p>
</div>
</div>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/jquery.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-transition.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-dropdown.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-tab.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-tooltip.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-popover.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-button.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-collapse.js"></script>
<script type="text/javascript" src="http://twitter.github.com/bootstrap/assets/js/bootstrap-carousel.js"></script>
<script type="text/javascript"
src="http://twitter.github.com/bootstrap/assets/js/google-code-prettify/prettify.js"></script>
</body>
</html>