Skip to content

Commit 47066e7

Browse files
mheverymhevery
committed
added documentation for ng:include and ng:widget and test for doc collector.
1 parent c0d30ae commit 47066e7

12 files changed

Lines changed: 374 additions & 31 deletions

File tree

‎docs/collect.js‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
require.paths.push("./lib");
2+
require.paths.push(__dirname);
13
var fs = require('fs'),
24
spawn = require('child_process').spawn,
3-
mustache = require('../lib/mustache'),
4-
callback = require('./callback'),
5-
markdown = require('../lib/markdown');
5+
mustache = require('mustache'),
6+
callback = require('callback'),
7+
markdown = require('markdown');
68

79
var documentation = {
810
section:{},
@@ -44,7 +46,7 @@ var work = callback.chain(function () {
4446
mergeTemplate('wiki_widgets.js', 'wiki_widgets.js', documentation, callback.chain());
4547
console.log('DONE');
4648
});
47-
work();
49+
if (!this.testmode) work();
4850
////////////////////
4951

5052
function noop(){}
@@ -78,6 +80,10 @@ function mergeTemplate(template, output, doc, callback){
7880
}
7981

8082

83+
function trim(string) {
84+
return string.replace(/^[\s\n\r]+/g, '').replace(/[\s\n\r]+$/g, '');
85+
}
86+
8187
function unknownTag(doc, name) {
8288
var error = "[" + doc.raw.file + ":" + doc.raw.line + "]: unknown tag: " + name;
8389
console.log(error);
@@ -93,7 +99,7 @@ function escapedHtmlTag(doc, name, value) {
9399
}
94100

95101
function markdownTag(doc, name, value) {
96-
doc[name] = markdown.toHTML(value);
102+
doc[name] = markdown.toHTML(value.replace(/^#/gm, '##'));
97103
}
98104

99105
var TAG = {
@@ -103,8 +109,10 @@ var TAG = {
103109
namespace: valueTag,
104110
css: valueTag,
105111
see: valueTag,
112+
usageContent: valueTag,
106113
'function': valueTag,
107114
description: markdownTag,
115+
TODO: markdownTag,
108116
returns: markdownTag,
109117
name: function(doc, name, value) {
110118
doc.name = value;
@@ -113,13 +121,13 @@ var TAG = {
113121
param: function(doc, name, value){
114122
doc.param = doc.param || [];
115123
doc.paramRest = doc.paramRest || [];
116-
var match = value.match(/^({([^\s=]+)(=)?}\s*)?([^\s]+|\[(\S+)+=([^\]]+)\])\s+(.*)/);
124+
var match = value.match(/^({([^\s=]+)(=)?}\s*)?(([^\s=]+)|\[(\S+)+=([^\]]+)\])\s+(.*)/);
117125
if (match) {
118126
var param = {
119127
type: match[2],
120-
name: match[4] || match[5],
121-
'default':match[6],
122-
description:match[7]};
128+
name: match[6] || match[5],
129+
'default':match[7],
130+
description:match[8]};
123131
doc.param.push(param);
124132
if (!doc.paramFirst) {
125133
doc.paramFirst = param;
@@ -138,11 +146,11 @@ function parseNgDoc(doc){
138146
var atText;
139147
var match;
140148
doc.raw.text.split(/\n/).forEach(function(line, lineNumber){
141-
if (match = line.match(/^@(\w+)(\s+(.*))?/)) {
149+
if (match = line.match(/^\s*@(\w+)(\s+(.*))?/)) {
142150
// we found @name ...
143151
// if we have existing name
144152
if (atName) {
145-
(TAG[atName] || unknownTag)(doc, atName, atText.join('\n'));
153+
(TAG[atName] || unknownTag)(doc, atName, trim(atText.join('\n')));
146154
}
147155
atName = match[1];
148156
atText = [];
@@ -178,8 +186,9 @@ function findNgDoc(file, callback) {
178186
if (inDoc && line.match(/\*\//)) {
179187
doc.raw.text = doc.raw.text.join('\n');
180188
doc.raw.text = doc.raw.text.replace(/^\n/, '');
181-
if (doc.raw.text.match(/@ngdoc/))
189+
if (doc.raw.text.match(/@ngdoc/)){
182190
callback(doc);
191+
}
183192
doc = null;
184193
inDoc = false;
185194
}

‎docs/filter.template‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ angular.filter.{{shortName}}({{paramFirst.name}}{{#paramRest}}, {{name}}{{/param
1515
<h3>Parameters</h3>
1616
<ul>
1717
{{#param}}
18-
<li><tt>{{name}}{{#type}}({{type}}){{/type}}</tt>: {{description}}</li>
18+
<li><tt>{{name}}:{{#type}}{{type}}{{/type}}{{^type}}:*{{/type}}{{#default}}={{default}}{{/default}}</tt>: {{{description}}}</li>
1919
{{/param}}
2020
</ul>
2121

‎docs/index.html‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,29 @@
66
<script type="text/javascript" src="../angular.min.js" ng:autobind></script>
77
<script type="text/javascript" src="http://angularjs.org/extensions/wiki_widgets.js"></script>
88
<link rel="stylesheet" href="http://angularjs.org/extensions/wiki_widgets.css" type="text/css" media="screen" />
9+
<script type="text/javascript">
10+
function DocsController() {
11+
this.docs = NG_DOC;
12+
window.$root = this.$root;
13+
14+
this.getUrl = function(page){
15+
return '#' + encodeURIComponent(page.name);
16+
}
17+
}
18+
</script>
919
</head>
10-
<body ng:init="docs=$window.NG_DOC; $window.$root = $root">
20+
<body ng:controller="DocsController">
1121
<table>
1222
<tr>
1323
<td valign="top">
1424
<div ng:repeat="(name, type) in docs.section">
1525
<b>{{name}}</b>
1626
<div ng:repeat="page in type">
17-
<a href="#{{page.name}}"><tt>{{page.shortName}}</tt></a>
27+
<a href="{{getUrl(page)}}"><tt>{{page.shortName}}</tt></a>
1828
</div>
1929
</div>
2030
</td>
21-
<td valign="top"><ng:include src="$location.hashPath + '.html' "></ng:include></td>
31+
<td valign="top"><ng:include src=" './' + $location.hashPath + '.html' "></ng:include></td>
2232
</tr>
2333
</table>
2434
</body>

‎docs/overview.template‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1-
{{{description}}}
1+
<h1><tt>{{name}}</tt></h1>
2+
{{{description}}}
3+
4+
<WIKI:SOURCE style="display:block;">
5+
{{{example}}}
6+
</WIKI:SOURCE>

‎docs/spec/collectSpec.js‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
console.log(__dirname);
2+
require.paths.push(__dirname + "/../");
3+
require.paths.push(__dirname + "/../../");
4+
var fs = require('fs');
5+
var Script = process.binding('evals').Script;
6+
var collect = load('docs/collect.js');
7+
8+
describe('collect', function(){
9+
describe('TAG', function(){
10+
var TAG = collect.TAG;
11+
describe('@param', function(){
12+
var doc;
13+
beforeEach(function(){
14+
doc = {};
15+
});
16+
it('should parse with no default', function(){
17+
TAG.param(doc, 'param',
18+
'{(number|string)} number Number to format.');
19+
expect(doc.param).toEqual([{
20+
type : '(number|string)',
21+
name : 'number',
22+
'default' : undefined,
23+
description : 'Number to format.' }]);
24+
});
25+
it('should parse with default', function(){
26+
TAG.param(doc, 'param',
27+
'{(number|string)=} [fractionSize=2] desc');
28+
expect(doc.param).toEqual([{
29+
type : '(number|string)',
30+
name : 'fractionSize',
31+
'default' : '2',
32+
description : 'desc' }]);
33+
});
34+
});
35+
});
36+
});
37+
38+
function load(path){
39+
var sandbox = {
40+
require: require,
41+
console: console,
42+
__dirname: __dirname,
43+
testmode: true
44+
};
45+
Script.runInNewContext(fs.readFileSync(path), sandbox, path);
46+
return sandbox;
47+
}

‎docs/specs.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
require.paths.push("./lib");
2+
var jasmine = require('jasmine-1.0.1');
3+
var sys = require('sys');
4+
5+
for(var key in jasmine) {
6+
global[key] = jasmine[key];
7+
}
8+
9+
var isVerbose = false;
10+
var showColors = true;
11+
process.argv.forEach(function(arg){
12+
switch(arg) {
13+
case '--color': showColors = true; break;
14+
case '--noColor': showColors = false; break;
15+
case '--verbose': isVerbose = true; break;
16+
}
17+
});
18+
19+
jasmine.executeSpecsInFolder(__dirname + '/spec', function(runner, log){
20+
process.exit(runner.results().failedCount);
21+
}, isVerbose, showColors);

‎docs/widget.template‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<h1><tt>{{name}}</tt></h1>
2+
<h2>Usage</h2>
3+
<h3>In HTML Template Binding</h3>
4+
<tt>
5+
<pre>
6+
&lt;{{shortName}}{{#param}} {{#default}}<i>[</i>{{/default}}{{name}}="..."{{#default}}<i>]</i>{{/default}}{{/param}}&gt;{{#usageContent}}
7+
8+
{{usageContent}}
9+
{{/usageContent}}&lt;/{{shortName}}&gt;
10+
</pre>
11+
</tt>
12+
13+
<h3>Parameters</h3>
14+
<ul>
15+
{{#param}}
16+
<li><tt>{{name}}:{{#type}}{{type}}{{/type}}{{^type}}:*{{/type}}{{#default}}={{default}}{{/default}}</tt>: {{{description}}}</li>
17+
{{/param}}
18+
</ul>
19+
20+
<h3>CSS</h3>
21+
{{{css}}}
22+
23+
<h2>Description</h2>
24+
{{{description}}}
25+
26+
<WIKI:SOURCE style="display:block;">
27+
{{{example}}}
28+
</WIKI:SOURCE>

‎gen_docs.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
#!/bin/sh
22

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

0 commit comments

Comments
 (0)