Deprecated

This repo is no longer maintained as jsdoc has implemented most of the features please use jsdoc instead

Coddoc

Description

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 coddoc.addTagHandler and coddoc.addCodeHandler. coddoc also parses source code to be used in APIs.

Coddoc also supports the generation of markdown and html through the use of different templates. Currently the templates use Handlebars but you may use any templating engine you wish

JSDOC Tags

JSDoc tags currently supported are:

• augments|extends : extend an object
• lends : document all members of an anonymous object as members of a declared symbol
• namespace : document a namespace
• parameter|param|arg|argument : parameters of a function
• return|returns : return value of a function
• memberof|memberOf : explicitly document a cod block as a member of an object
• name : explicitly document the name of a symbol
• constructor|constructs : document a symbol as a constructor for a class
• class : documents a symbol as a class
• classdesc : alternate way to add a description to a class
• example : document an example/s of a symbol
• private : document a symbol as private.
• ignore : allows you to document a symbol but ignore it in parsing
• method|function : explicily document a symbol as a method
• field : explicily document a symbol as a field
• type : document the type of a field
• default : document the default value of a field
• throws|throw|exception : document any exception thrown by a method
• property : document a property in the constructor declaration of a class
• borrows : document any filed/methods borrowed from a class
• constant|const : document a field as a constant
• desc|description : alternate way to explicitly document the description of a symbol
• public:explicitly document a symbol as public

Coddoc Tags

Coddoc also has a few additional tags.

• ignoreCode : ignore the parsed code in the output
• includeDoc : include an external doc. External docs can be html or markdown. Example

  @includeDoc [Title Of Doc] ../location/of_doc.md

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

  {@code var test = "test"; }

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

  Installation

  Locally ```javascript npm install coddoc ``` Globally

   npm install -g coddoc

  Usage

  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

  • -d --directory : the directory that contains your code
  • [-f --formatter] : optional formatter to use, if not specified then a JSON object of the symbols will be output
  • [-p --pattern] : optional file pattern to use when searching for files

  Examples

  JSON output

   coddoc -d ./lib > symbols.json

  To use the markdown formatter

   coddoc -d ./lib -f markdown > README.md

  To use the HTML formatter

   coddoc -d ./lib -f html > index.html

  To use pragmatically

  var coddoc = require("coddoc");
  var tree = coddoc.parse({directory : __dirname + "/lib"});
  var classes = tree.classes, namespaces = tree.namespaces;
  //do something

  API

  ##Namespaces

  • coddoc

  ##Classes

  • coddoc.Context

  • coddoc.Symbol

  • coddoc.Tree

  ##coddoc

  Top

  Entry point for parsing code.

  • addCodeHandler

  • addTagHandler

  • getTagRegexp

  • parse

  • parseCode

  • parseTag

  ###addCodeHandler static function public

  ---

  Defined parser/code.js Top

  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 Top

  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 Top

  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 Top

  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 Top

  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 Top

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

  ##coddoc.Context

  Top

  A Context object used to keep state when parsing symbols. The context should not be used directly by user code.

  Instance

  • activateScope

  • addNamespace

  • addScope

  • getActiveScope

  • getActiveScopeName

  • getNamespace

  • getScope

  ###Constructor

  Defined context.js Top

  Source

  function (){
     this.scopes = {};
     this.nameSpaces = {global:[]};
     this.aliases = {};
     this.activateScope("global");
         
  }

  ###activateScope function public

  ---

  Defined context.js Top

  Activates a scope for.

  Arguments

  • name : the name of the scope.

  Returns

  • Object the activated scope object.

  Source

  function (name){
     this.activeScope = name;
     return this.addScope(name);
         
  }

  ###addNamespace function public

  ---

  Defined context.js Top

  Adds a namespace the the context object.

  Arguments

  • name : the name of the namespace

  Returns

  • Object the object for the namespace.

  Source

  function (name){
     if ("undefined" === typeof this.nameSpaces[name]) {
         this.nameSpaces[name] = {};
     }
     return this.nameSpaces[name];
         
  }

  ###addScope function public

  ---

  Defined context.js Top

  Adds a scope to the context

  Arguments

  • name : the name of the scope to add,

  Returns

  • Object the object for the namespace.

  Source

  function (name){
     if ("undefined" === typeof this.scopes[name]) {
         this.scopes[name] = {};
     }
     return this.scopes[name];
         
  }

  ###getActiveScope function public

  ---

  Defined context.js Top

  Returns the active scope.

  Returns

  • Object the scope object

  Source

  function (){
     return this.getScope(this.activeScope);
         
  }

  ###getActiveScopeName function public

  ---

  Defined context.js Top

  Returns the name of the active scope.

  Returns

  • String the active scope name.

  Source

  function (){
     return this.activeScope;
         
  }

  ###getNamespace function public

  ---

  Defined context.js Top

  Gets a namespace, creating it if it does not exist.

  Arguments

  • name : the name of the context

  Returns

  • Object the object for the namespace.

  Source

  function (name){
     return this.addNamespace(name);
         
  }

  ###getScope function public

  ---

  Defined context.js Top

  Gets a scope creating it if it does not exist.

  Arguments

  • name : the name of the scope to get,

  Returns

  • Object the object for the namespace.

  Source

  function (name){
     return this.addScope(name);
         
  }

  ##coddoc.Symbol

  Top

  A Symbol represents a comment and code pair. Each code handler added through coddoc.addCodeHandler and tag handler added through coddoc.addTagHandler adds/removes properties from a the symbol. Each symbol is added to the coddoc.Tree which is either returned from coddoc or passed into a template handler.

  NOTE: This object should not be instantiated by user code

  Instance Properties

  Property	Type	Default Value	Description
  augments	{Array}	[]	Any symbols this symbol augments
  borrows	{Array}	[]	Any properties this symbol borrows
  codeObject	{Object}	null	The codeObject of this symbol
  description	{String}	""	The description of this symbol.
  examples	{Array}	[]	The examples for this symbol
  file	{String}	""	The file where the symbol was found.
  fullname	{String}	""	The fullname i.e ({memberof}.{name})
  ignore	{Boolean}	false	Set to true if the symbol should be ignored and not put into coddoc.Tree
  ignoreCode	{Boolean}	false	Set to true if the code object from this symbol should be ignored.
  isConstant	{Boolean}	false	Set to true if this symbol is a constant.
  isConstructor	{Boolean}	false	Set to true is this symbol is a constructor
  isFunction	{Boolean}	false	Set to true if this symbol is a function.
  isPrivate	{Boolean}	false	Set to true if this symbol is private.
  isProtected	{Boolean}	false	Set to true if this symbol is protected.
  isStatic	{Boolean}	false	Set to true if this symbol is static
  memberof	{String}	""	Who this symbol belongs to.
  name	{String}	""	The name of this symbol
  params	{Array}	[]	The associated params for this symbol if it is a funciton.
  properties	{Array}	[]	The associated properties for this symbol
  returns	{Array}	[]	Array of return types for this symbol
  see	{Array}	[]	Any link for this symbol
  tags	{Array}	[]	The associated tags for this symbol
  throws	{Array}	[]	Exceptions thrown by this symbol
  type	{*}	null	The type that is symbol represents.

  ###Constructor

  Defined symbol.js Top

  Arguments

  • options : 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.

  Source

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

  ##coddoc.Tree

  Top

  A Tree object which contains symbols.

  Instance

  • _addSymbol

  • addSymbol

  • getClasses

  • getMembers

  • getNamespaces

  • getSymbol

  • hasSymbol

  ###Constructor

  Defined tree.js Top

  Source

  function (){
     this.symbols = {global:[]};
         
  }

  ###_addSymbol function private

  ---

  Defined tree.js Top

  Adds a symbol to this tree.

  Arguments

  • name : the name of the symbol to add.

  Returns

  • Array

  Source

  function (name){
     var ret = this.symbols[name];
     if (!ret) {
         ret = this.symbols[name] = [];
     }
     return ret;
         
  }

  ###addSymbol function public

  ---

  Defined tree.js Top

  Entry point to add the symbol

  Arguments

  • symbol :

  • path String : the path of the symbol. i.e the memberof property of a symbol

  • name :

  • obj :

  Source

  function (symbol){
     var nameParts = utils.splitName(symbol.fullName);
     var path = nameParts.memberof, name = nameParts.name;
     if (path === "global") {
         path = name;
     }
     var sym = this.getSymbol(path);
     sym.push(symbol);
         
  }

  ###getClasses function public

  ---

  Defined tree.js Top

  Returns all classes in the tree. The following properties are added to each class symbol.

  • staticMethods : all static methods for the class
  • staticProperties : all static properties for the class
  • instanceMethods : all isntance methods for the class
  • instanceProperties : all instance properties for a class

  Returns

  • Array

  Source

  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 + ".prototype"] || [];
         var borrowedMethods = [], borrowedProperties = [], staticBorrowedMethods = [], staticBorrowedProperties = [];
         s.borrows.map(function (b) {
             var borrows = b.borrows;
             var symbol = symbols[borrows.memberof || "global"].filter(function (s) {
                 return s.name === borrows.name;
             });
             if (symbol.length) {
                 symbol = symbol[0];
                 var memberof = b.isStatic ? name : name + ".prototype";
                 var newSymb = new Symbol(utils.merge({}, symbol, {name:b.as, isStatic:b.isStatic, fullName:memberof + "." + 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 && !s.isConstructor;
             }).concat(staticBorrowedMethods);
         s.staticProperties = statics.filter(
             function (s) {
                 return !s.isFunction && !s.isNamespace;
             }).concat(staticBorrowedProperties);
         s.instanceMethods = instance.filter(
             function (s) {
                 return s.isFunction && !s.isConstructor;
             }).concat(borrowedMethods);
         s.instanceProperties = instance.filter(
             function (s) {
                 return !s.isFunction && !s.isNamespace;
             }).concat(s.properties || []).concat(borrowedProperties);
         return s;
     });
         
  }

  ###getMembers function public

  ---

  Defined tree.js Top

  Gets all members( coddoc.Symbol) for a particular path.

  Arguments

  • path : the path to look up.

  Returns

  • Array and array of symbols.

  Source

  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 && !s.isConstructor && s.memberof === path;
         }));
     });
     return namespaces;
         
  }

  ###getNamespaces function public

  ---

  Defined tree.js Top

  Returns all namespaces in this tree. This method also adds the following values to the namespace.

  • properties : all properties that belong to the namespace
  • methods : all methods that belong to the namespace

  Returns

  • Array array of namespaces

  Source

  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 && s.memberof !== "global" ? [s.memberof, s.name].join(".") : 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);
         
  }

  ###getSymbol function public

  ---

  Defined tree.js Top

  Returns a symbol from this tree. The Tree will create the symbol if it does not exist.

  Arguments

  • name : the name of the symbol to get

  Returns

  • Array the array for the symbol.

  Source

  function (name){
     return this._addSymbol(name);
         
  }

  ###hasSymbol function public

  ---

  Defined tree.js Top

  Returns true if this tree contains a symbol.

  Arguments

  • name : the name to test if the tree contains the symbol

  Returns

  • Boolean true if the tree contains the symbol.

  Source

  function (name){
     var parts = name.split(".");
     return !!this.symbols[name];
         
  }

  License

  MIT LICENSE

  Meta

  ---

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