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 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 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 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 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 Returns 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 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 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