Skip to content

Commit

Permalink
added documentation for ng:include and ng:widget and test for doc col…
Browse files Browse the repository at this point in the history
…lector.
  • Loading branch information
mhevery committed Nov 4, 2010
1 parent c0d30ae commit 47066e7
Show file tree
Hide file tree
Showing 12 changed files with 374 additions and 31 deletions.
33 changes: 21 additions & 12 deletions docs/collect.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
require.paths.push("./lib");
require.paths.push(__dirname);
var fs = require('fs'),
spawn = require('child_process').spawn,
mustache = require('../lib/mustache'),
callback = require('./callback'),
markdown = require('../lib/markdown');
mustache = require('mustache'),
callback = require('callback'),
markdown = require('markdown');

var documentation = {
section:{},
Expand Down Expand Up @@ -44,7 +46,7 @@ var work = callback.chain(function () {
mergeTemplate('wiki_widgets.js', 'wiki_widgets.js', documentation, callback.chain());
console.log('DONE');
});
work();
if (!this.testmode) work();
////////////////////

function noop(){}
Expand Down Expand Up @@ -78,6 +80,10 @@ function mergeTemplate(template, output, doc, callback){
}


function trim(string) {
return string.replace(/^[\s\n\r]+/g, '').replace(/[\s\n\r]+$/g, '');
}

function unknownTag(doc, name) {
var error = "[" + doc.raw.file + ":" + doc.raw.line + "]: unknown tag: " + name;
console.log(error);
Expand All @@ -93,7 +99,7 @@ function escapedHtmlTag(doc, name, value) {
}

function markdownTag(doc, name, value) {
doc[name] = markdown.toHTML(value);
doc[name] = markdown.toHTML(value.replace(/^#/gm, '##'));
}

var TAG = {
Expand All @@ -103,8 +109,10 @@ var TAG = {
namespace: valueTag,
css: valueTag,
see: valueTag,
usageContent: valueTag,
'function': valueTag,
description: markdownTag,
TODO: markdownTag,
returns: markdownTag,
name: function(doc, name, value) {
doc.name = value;
Expand All @@ -113,13 +121,13 @@ var TAG = {
param: function(doc, name, value){
doc.param = doc.param || [];
doc.paramRest = doc.paramRest || [];
var match = value.match(/^({([^\s=]+)(=)?}\s*)?([^\s]+|\[(\S+)+=([^\]]+)\])\s+(.*)/);
var match = value.match(/^({([^\s=]+)(=)?}\s*)?(([^\s=]+)|\[(\S+)+=([^\]]+)\])\s+(.*)/);
if (match) {
var param = {
type: match[2],
name: match[4] || match[5],
'default':match[6],
description:match[7]};
name: match[6] || match[5],
'default':match[7],
description:match[8]};
doc.param.push(param);
if (!doc.paramFirst) {
doc.paramFirst = param;
Expand All @@ -138,11 +146,11 @@ function parseNgDoc(doc){
var atText;
var match;
doc.raw.text.split(/\n/).forEach(function(line, lineNumber){
if (match = line.match(/^@(\w+)(\s+(.*))?/)) {
if (match = line.match(/^\s*@(\w+)(\s+(.*))?/)) {
// we found @name ...
// if we have existing name
if (atName) {
(TAG[atName] || unknownTag)(doc, atName, atText.join('\n'));
(TAG[atName] || unknownTag)(doc, atName, trim(atText.join('\n')));
}
atName = match[1];
atText = [];
Expand Down Expand Up @@ -178,8 +186,9 @@ function findNgDoc(file, callback) {
if (inDoc && line.match(/\*\//)) {
doc.raw.text = doc.raw.text.join('\n');
doc.raw.text = doc.raw.text.replace(/^\n/, '');
if (doc.raw.text.match(/@ngdoc/))
if (doc.raw.text.match(/@ngdoc/)){
callback(doc);
}
doc = null;
inDoc = false;
}
Expand Down
2 changes: 1 addition & 1 deletion docs/filter.template
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ angular.filter.{{shortName}}({{paramFirst.name}}{{#paramRest}}, {{name}}{{/param
<h3>Parameters</h3>
<ul>
{{#param}}
<li><tt>{{name}}{{#type}}({{type}}){{/type}}</tt>: {{description}}</li>
<li><tt>{{name}}:{{#type}}{{type}}{{/type}}{{^type}}:*{{/type}}{{#default}}={{default}}{{/default}}</tt>: {{{description}}}</li>
{{/param}}
</ul>

Expand Down
16 changes: 13 additions & 3 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,29 @@
<script type="text/javascript" src="../angular.min.js" ng:autobind></script>
<script type="text/javascript" src="http://angularjs.org/extensions/wiki_widgets.js"></script>
<link rel="stylesheet" href="http://angularjs.org/extensions/wiki_widgets.css" type="text/css" media="screen" />
<script type="text/javascript">
function DocsController() {
this.docs = NG_DOC;
window.$root = this.$root;

this.getUrl = function(page){
return '#' + encodeURIComponent(page.name);
}
}
</script>
</head>
<body ng:init="docs=$window.NG_DOC; $window.$root = $root">
<body ng:controller="DocsController">
<table>
<tr>
<td valign="top">
<div ng:repeat="(name, type) in docs.section">
<b>{{name}}</b>
<div ng:repeat="page in type">
<a href="#{{page.name}}"><tt>{{page.shortName}}</tt></a>
<a href="{{getUrl(page)}}"><tt>{{page.shortName}}</tt></a>
</div>
</div>
</td>
<td valign="top"><ng:include src="$location.hashPath + '.html' "></ng:include></td>
<td valign="top"><ng:include src=" './' + $location.hashPath + '.html' "></ng:include></td>
</tr>
</table>
</body>
Expand Down
7 changes: 6 additions & 1 deletion docs/overview.template
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
{{{description}}}
<h1><tt>{{name}}</tt></h1>
{{{description}}}

<WIKI:SOURCE style="display:block;">
{{{example}}}
</WIKI:SOURCE>
47 changes: 47 additions & 0 deletions docs/spec/collectSpec.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
console.log(__dirname);
require.paths.push(__dirname + "/../");
require.paths.push(__dirname + "/../../");
var fs = require('fs');
var Script = process.binding('evals').Script;
var collect = load('docs/collect.js');

describe('collect', function(){
describe('TAG', function(){
var TAG = collect.TAG;
describe('@param', function(){
var doc;
beforeEach(function(){
doc = {};
});
it('should parse with no default', function(){
TAG.param(doc, 'param',
'{(number|string)} number Number to format.');
expect(doc.param).toEqual([{
type : '(number|string)',
name : 'number',
'default' : undefined,
description : 'Number to format.' }]);
});
it('should parse with default', function(){
TAG.param(doc, 'param',
'{(number|string)=} [fractionSize=2] desc');
expect(doc.param).toEqual([{
type : '(number|string)',
name : 'fractionSize',
'default' : '2',
description : 'desc' }]);
});
});
});
});

function load(path){
var sandbox = {
require: require,
console: console,
__dirname: __dirname,
testmode: true
};
Script.runInNewContext(fs.readFileSync(path), sandbox, path);
return sandbox;
}
21 changes: 21 additions & 0 deletions docs/specs.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
require.paths.push("./lib");
var jasmine = require('jasmine-1.0.1');
var sys = require('sys');

for(var key in jasmine) {
global[key] = jasmine[key];
}

var isVerbose = false;
var showColors = true;
process.argv.forEach(function(arg){
switch(arg) {
case '--color': showColors = true; break;
case '--noColor': showColors = false; break;
case '--verbose': isVerbose = true; break;
}
});

jasmine.executeSpecsInFolder(__dirname + '/spec', function(runner, log){
process.exit(runner.results().failedCount);
}, isVerbose, showColors);
28 changes: 28 additions & 0 deletions docs/widget.template
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<h1><tt>{{name}}</tt></h1>
<h2>Usage</h2>
<h3>In HTML Template Binding</h3>
<tt>
<pre>
&lt;{{shortName}}{{#param}} {{#default}}<i>[</i>{{/default}}{{name}}="..."{{#default}}<i>]</i>{{/default}}{{/param}}&gt;{{#usageContent}}

{{usageContent}}
{{/usageContent}}&lt;/{{shortName}}&gt;
</pre>
</tt>

<h3>Parameters</h3>
<ul>
{{#param}}
<li><tt>{{name}}:{{#type}}{{type}}{{/type}}{{^type}}:*{{/type}}{{#default}}={{default}}{{/default}}</tt>: {{{description}}}</li>
{{/param}}
</ul>

<h3>CSS</h3>
{{{css}}}

<h2>Description</h2>
{{{description}}}

<WIKI:SOURCE style="display:block;">
{{{example}}}
</WIKI:SOURCE>
2 changes: 1 addition & 1 deletion gen_docs.sh
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
#!/bin/sh

/usr/local/bin/node docs/collect.js
/usr/local/bin/node docs/specs.js --noColor && /usr/local/bin/node docs/collect.js
Loading

0 comments on commit 47066e7

Please sign in to comment.