Skip to content

Render formatted examples description params #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dandandan1503 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Render formatted examples description params #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a1189c6
* Update where $compile is called in `ngExampleContainer` so it will …
dandandan1503 Nov 3, 2015
19d6722
Added formatting of method return values
dandandan1503 Nov 6, 2015
cab6ebd
Fix formatting if there are multiple (potential) return types
dandandan1503 Nov 6, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 84 additions & 50 deletions core/parser.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,34 @@ var eid = 1;
var Parser = function () {};

Parser.prototype = nodeExtend(Parser.prototype, {
// Parse return values for formatting
parseReturns: function(returns) {
var returnsData = {
type: [],
content: null
};

var chunks = returns.match(/({([^\}]+)})?\s*([\s\S]+)/);
if(!chunks) {
return false;
}
var types = chunks[2] ? chunks[2].match(/([\w]+((\.[\w<\.\(\)]+\|?[\w\(\)>]+)|\([\w]+\))?)=?/g) : null;
if(types) {
returnsData.type = types.map(function (type) {
if(type.indexOf('=') !== -1) { returnsData.optional = true; }
type = type.replace(/=.*/, '');
return {
name: type,
type: (type.indexOf('function') !== -1 ? 'function' : type).toLowerCase()
};
})
}
if(chunks.length >= 4) {
returnsData.content = chunks[3];
}

return returnsData;
},

parseParam: function (param) {
var paramData = {
Expand All @@ -19,7 +47,7 @@ Parser.prototype = nodeExtend(Parser.prototype, {
optional: false,
defaultValue: null
};

//I hate regexes. Seriously.
var chunks = param.match(/({([^\}]+)})?\s*([\[\]\=\w\|]+)\s+([\s\S]+)/);

Expand All @@ -38,7 +66,7 @@ Parser.prototype = nodeExtend(Parser.prototype, {
};
})
}

paramData.varName = chunks[3].replace('[', '').replace(']', '');
if(paramData.varName.indexOf('|') !== -1) {
var names = paramData.varName.split('|');
Expand All @@ -50,19 +78,19 @@ Parser.prototype = nodeExtend(Parser.prototype, {
defaultValue = defaultValue[1];
paramData.varName = paramData.varName.replace('=' + defaultValue, '');
}

paramData.defaultValue = defaultValue;
paramData.description = chunks[4];

return paramData;
},

parseDocumentationChunk: function (docChunk, isngdoc, defaultModule) {
var docItems, docItem, ngdocParamFound = false, docGroup = {
params: [],
docType: 'ngdoc'
}, i, l, docItemContent, docItemKey;

if(!isngdoc) {
docItems = docChunk.match(/\*\s*@(?:(?!\s*\*\s*@)[\s\S])+/gm);
} else {
Expand All @@ -77,7 +105,7 @@ Parser.prototype = nodeExtend(Parser.prototype, {
ngdocParamFound = true;
}
}

//Exit if not angular doc - helps prevent errors
if(!ngdocParamFound) { return false; }
var parentDoc, parentName;
Expand All @@ -87,19 +115,19 @@ Parser.prototype = nodeExtend(Parser.prototype, {
docItem = docItem.replace('@description', '@description ');
}
var matches = docItem.match(/@([\w\d]+)\s*([\s\S]+)?/);

if(!matches) {
return false;
}

docItemKey = matches[1];
docItemContent = matches[2] || '';
docItemContent = docItemContent.replace(/[\n\r\s]+$/, '')
if(docItemKey === 'description' && isngdoc) {
docItemContent = docChunk.match(/@description([\s\S]+)/);
docItemContent = docItemContent[1];
}

switch(docItemKey) {
case 'param':
var param = this.parseParam(docItemContent);
Expand All @@ -108,47 +136,53 @@ Parser.prototype = nodeExtend(Parser.prototype, {
} else {
console.error("Invalid param: " + docItemContent);
}
break;
case 'property':
break;
case "returns":
var returns = this.parseReturns(docItemContent);
docGroup[docItemKey] = returns || '';
break;
break;
case 'property':
if(!docGroup.property) {
docGroup.property = [];
}
docGroup.property.push(this.parseParam(docItemContent))
break;
break;
case 'deprecated':
case 'scope':
docGroup[docItemKey] = true;
break;
break;
case 'requires':
if(!docGroup.requires) {
docGroup.requires = [];
}
docGroup.requires.push(docItemContent);
break;
break;
case 'methodOf':
case 'propertyOf':
case 'eventOf':
case 'memberOf': //Non standard, but needed for organization
docGroup[docItemKey] = docItemContent;
parentDoc = docItemContent;
break;
break;
case "name":
if(docGroup.ngdoc === 'method' || docGroup.ngdoc === 'property' || docGroup.ngdoc === 'event' || docGroup.ngdoc === 'constant' || docGroup.ngdoc === 'provider' || docGroup.ngdoc === 'service' || docGroup.ngdoc === 'directive' || docGroup.ngdoc === 'function' || docGroup.ngdoc === 'type' || docGroup.ngdoc === 'overview') {
var sep = Math.max(docItemContent.indexOf(':'), docItemContent.indexOf('#'));
if (sep >= 0) {
parentDoc = docItemContent.substr(0, sep);
docItemContent = docItemContent.substr(sep+1);
var sep = Math.max(docItemContent.indexOf(':'), docItemContent.indexOf('#'));
if (sep >= 0) {
parentDoc = docItemContent.substr(0, sep);
docItemContent = docItemContent.substr(sep+1);
}
} else if(docGroup.ngdoc == 'module') {
docGroup.module = docItemContent;
}
/*falls through*/
default:

default:
docGroup[docItemKey] = docItemContent;
break;
}
}

var replaceables = ['method', 'property', 'event', 'constant', 'provider', 'service', 'function', 'type', 'directive'];

if(docGroup.name) {
Expand All @@ -169,56 +203,56 @@ Parser.prototype = nodeExtend(Parser.prototype, {
parentDoc = parentDoc.replace(re, '');
}

var sep = parentDoc.indexOf(':');
if(sep >= 0)
{
docGroup.module = parentDoc.substr(0, sep);
parentDoc = parentDoc.substr(sep+1);
}
else
docGroup.module = parentDoc;

docGroup.parentDoc = {
module: docGroup.module,
name: parentDoc
};
}
var sep = parentDoc.indexOf(':');
if(sep >= 0)
{
docGroup.module = parentDoc.substr(0, sep);
parentDoc = parentDoc.substr(sep+1);
}
else
docGroup.module = parentDoc;

docGroup.parentDoc = {
module: docGroup.module,
name: parentDoc
};
}
} else if (docGroup.ngdoc === 'overview' || docGroup.ngdoc === 'tutorial') {
docGroup.parentDoc = {};
}
if(!docGroup.module && defaultModule) {
docGroup.module = defaultModule;
}

if(!docGroup.module && defaultModule) {
docGroup.module = defaultModule;
}

return docGroup;
},

parse: function (fileData, allFiles) {

var content = fileData.content, documentationChunks, isngdoc = false;
if(fileData.extension === 'ngdoc') {
documentationChunks = [content];
isngdoc = true;
} else {
documentationChunks = content.match(/\/\*{2,}(?:(?!\*{1,}\/)[\s\S])+/gm);
}

if(!documentationChunks) {
return false;
}

var results = [], defaultModule = null;
for(var i = 0, l = documentationChunks.length; i < l; i++) {
var result = this.parseDocumentationChunk(documentationChunks[i], isngdoc, defaultModule);
if(result) {
result.file = fileData.fileName;
results.push(result);
results.push(result);
}
}
return results;
},

backfill: function (fileData, allFiles) {
for(var i = 0, l = fileData.docs.length; i < l; i++) {
var doc = fileData.docs[i];
Expand All @@ -235,16 +269,16 @@ Parser.prototype = nodeExtend(Parser.prototype, {
}
}
},

guessModuleFromFiles: function (docModel, allFiles) {
var currentFile = docModel.file;
var fileMatcher = '[^\\/\\\\]+$';
var currentFolder = currentFile.replace(new RegExp(fileMatcher), '');

var module = this._findModuleDeclaration(currentFolder, allFiles);
return module;
},

_findModuleDeclaration: function (inFolder, allFiles) {
var fileMatcher = '[^\\/\\\\]+$';
var regex = new RegExp('^' + inFolder + fileMatcher);
Expand Down
10 changes: 6 additions & 4 deletions web/documentationPartial.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ <h2>Usage</h2>
</div>
</div>

<h5 ng-if="documentationItem.returns">Returns</h5>
<ng-example-container group='group' example="documentationItem.returns"></ng-example-container>
<div ng-if="documentationItem.returns">
<returns-content returns="documentationItem.returns"></returns-content>
</div>

<div ng-if="documentationItem.params.length &gt; 0" id="argumentSection">
<h2>Arguments</h2>
Expand All @@ -52,8 +53,9 @@ <h2>Methods</h2>
<h4><ng-method-usage-example item='documentationItem'></ng-method-usage-example></h4>
<ng-example-container group='group' example="documentationItem.description"></ng-example-container>
<param-list ng-if="documentationItem.params.length > 0" params="documentationItem.params"></param-list>
<h5 ng-if="documentationItem.returns">Returns</h5>
<ng-example-container group='group' example="documentationItem.returns"></ng-example-container>
<div ng-if="documentationItem.returns">
<returns-content returns="documentationItem.returns"></returns-content>
</div>
</div>
</div>

Expand Down
Loading