Defined index.js

Entry point for parsing code.

Example

var tree = coddoc({directory : path.resolve(__dirname + "lib")});

//To use markdown formatter
var doc = coddoc({directory : path.resolve(__dirname + "lib"), formatter : coddoc.formatters.markdown});

//To use html formatter
var doc = coddoc({directory : path.resolve(__dirname + "lib"), formatter : coddoc.formatters.html});

//To use custom file pattern
var doc = coddoc({directory : path.resolve(__dirname + "lib"), patter : /.+\.test\.js$/i, formatter : coddoc.html});
        

Arguments

• options : options object.
• options.dir String : the directory of code to parse.
• [options.pattern= /.+\.js$/i] RegExp : a regular expression to test files agains
• options.formatter? Object : And optional formatter to format the tree. The object must contain a generate method. See coddoc.formatters.html

Source

function (options){
   options = options || {};
   var baseDir = options.dir, filePattern = options.pattern || FILE_PATTERN;
   if (!baseDir) {
       console.log("directory required");
   }
   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() && filePattern.test(file)) {
               fileMap[filePath] = fs.readFileSync(filePath, "utf8");
           }
       });
   }(baseDir));
   var context = new Context(), tree = new Tree();
   Object.keys(fileMap).forEach(function (i, j) {
       emitter.emit("file", i);
       context.activateScope("global");
       parser.parse(fileMap[i], path.relative(baseDir, i), tree, context, emitter);
   });
   return tree;
       
}
    

addCodeHandler Static Function Public

---

Defined parser/code.js

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 RegExp.$ properties to access match sub expressions. By Default code blocks of the following form are parsed.

// /^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"
}

Example

var util = require("coddoc").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:'function',
         isFunction:true,
         memberof:activeScope,
         isStatic:activeScope ? !activeScope.match(".prototype") : false,
         isPrivate:name.match(/^_/) != null,
         name:name,
         params:params,
         code:['function (', params.map(
             function (n) {
                 return n.name.name;
             }).join(","), '){\n   ', util.getCode(str, "{").split("\n").join("\n   "), "\n}"].join("")
    };
});
        

Arguments

• regexp : the regular expression used to match code blocks.
• [priority= 0] : the priority to give this code handler if not provided it is defaulted to 0.
• parse : a function that returns an object. The object will be set as the codeObject on the coddoc.Symbol. The properties of the object will be added to the coddoc.Symbol for processing later.

Source

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);
       
}
    

addTagHandler Static Function Public

---

Defined parser/tags.js

Adds a new tag to be parsed. You can use this to add custom tags. coddoc will not do anything with the new tag by default, however you can add functionality to handle the new tag in the template.

Example

//if a tag is contains a '|' character then each variation will resolve the the same parser function.
coddoc.addTagHandler("void|VOID|Void", function(comment, symbol, context){
   //do something with the tag or add properties to the symbol.
   symbol.isVoid = true;
   symbol.tags.push({tag : "void", 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
<h3>
{{name}}
{{#if isStatic}}
<span class="label label-info">Static</span>
{{/if}}
{{#if isFunction}}
<span class="label label-label">Function</span>
{{/if}}
{{#if isPrivate}}
<span class="label label-important">Private</span>
{{else}}
     {{#if isProtected}}
<span class="label label-warning">Protected</span>
     {{else}}
<span class="label label-success">Public</span>
     {{/if}}
{{/if}}
{{#if isVoid}}
<span class="label label-label">Void</span>
{{/if}}
</h3>
        

Arguments

• tag : 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.
• parse : a parser function to invoke when a tag that matches the name is encountered.

Source

function (tag,parse){
   tag.split("|").forEach(function (tag) {
       tags[tag] = {
           parse:parse || function () {
               return {tag:tag, props:{}};
           }};
   });
       
}
    

getTagRegexp Static Function Protected

---

Defined parser/tags.js

Returns a regular expression that can be used to parse tags

Returns

• RegExp a regular expression to parse valid tags.

Source

function (){
   return new RegExp("@(" + Object.keys(tags).join("|") + ")");
       
}
    

parse Static Function Protected

---

Defined parser/index.js

Parses a string of code into coddoc.Symbols. All processed symbols are added to the coddoc.Tree. This method is not intended to be used directly by user code.

Arguments

• str : the source code to parse
• filepath : the relative filepath where the source is located. This is set on the symbol during parsing.
• tree : the tree which contains all symbols.
• context : the context which holds information about the current parsing job.
• emitter :

Returns

• Object

Source

function (str,filepath,tree,context,emitter){
   var l = str.length;
   var symbols = [];
   for (var i = 0; i < l; i++) {
       var tags = [];
       var comment = "", c = str[i], startIndex = i, endIndex, ret = [];
       var startCIndex = str.indexOf("/**", i);
       if (startCIndex !== -1) {
           i = startCIndex + 2;
           var endCIndex = str.indexOf("*/", i);
           if (endCIndex !== -1) {
               comment = str.substr(startCIndex + 2, endCIndex - (startCIndex + 2)).split("\n").map(joinAndReplace).join("\n");
               emitter.emit("comment", 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("symbol", sym);
               var memberof = sym.memberof;
               if (!sym.ignore && !sym.lends) {
                   tree.addSymbol(sym);
               }
           }
       } else {
           i++;
       }
   }
   return {symbols:symbols, code:str};
       
}
    

parseCode Static Function Protected

---

Defined parser/code.js

Uses Registered handlers to parse the next block of code from a code fragment. This function is used by coddoc.parse to parse code for comments.

Arguments

• str : the source string to parse
• symbol : the symbol to add parsed properties from.
• context : the current context

Source

function (str,symbol,context){
   var l = handlers.length, ret = {};
   for (var i = 0; i < 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];
       });
   }
       
}
    

parseTag Static Function Protected

---

Defined parser/tags.js

Parses a tag and the coresponding comment using a matching tag handler. Each parsed tag could add a new property to the coddoc.Symbol. The parsed tag will be added the the coddoc.Symbol#tags array.

Example

coddoc.parseTag("someTag", "@someTag props...", sym, src, index, context);
//would add a new tag to the symbols property
{
     tag : "tagname",
     props : {...}
}

//the props value would also be added to the symbols params array.
        

Arguments

• comment : the comment fragment being parsed
• sym : the symbol that the comment corresponds to. The code object and values will have already been set.
• context : the currect context object. The context allows tags to set new scopes and namespaces.
• tag String : the tag name being parsed from the comment

Source

function (comment,sym,context){
   var tag = comment.match(TAG_REGEXP), ret = {};
   if (tag && tag.length === 2) {
       var t = tags[tag[1]];
       if (t) {
           t.parse(comment, sym, context);
       } else {
           throw new Error("Invalid tag " + tag);
       }
   }
       
}
    

---

License

MIT LICENSE

Meta

---

Code: git clone git://github.com/pollenware/coddoc.git