From 47066e70e1621ff74bd2cd6b5853ca3c5841aba6 Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Thu, 4 Nov 2010 14:24:31 -0700
Subject: added documentation for ng:include and ng:widget and test for doc
 collector.

---
 docs/collect.js          | 33 +++++++++++++++++++++------------
 docs/filter.template     |  2 +-
 docs/index.html          | 16 +++++++++++++---
 docs/overview.template   |  7 ++++++-
 docs/spec/collectSpec.js | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/specs.js            | 21 +++++++++++++++++++++
 docs/widget.template     | 28 ++++++++++++++++++++++++++++
 7 files changed, 137 insertions(+), 17 deletions(-)
 create mode 100644 docs/spec/collectSpec.js
 create mode 100644 docs/specs.js
 create mode 100644 docs/widget.template

(limited to 'docs')

diff --git a/docs/collect.js b/docs/collect.js
index f85f2c6b..c16366ab 100644
--- a/docs/collect.js
+++ b/docs/collect.js
@@ -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:{},
@@ -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(){}
@@ -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);
@@ -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 = {
@@ -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;
@@ -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;
@@ -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 = [];
@@ -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;
       }
diff --git a/docs/filter.template b/docs/filter.template
index f9005782..0602aff9 100644
--- a/docs/filter.template
+++ b/docs/filter.template
@@ -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>
 
diff --git a/docs/index.html b/docs/index.html
index f61893a4..a2cad87e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -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>
diff --git a/docs/overview.template b/docs/overview.template
index dbb91e2a..c4c899e2 100644
--- a/docs/overview.template
+++ b/docs/overview.template
@@ -1 +1,6 @@
-{{{description}}}
\ No newline at end of file
+<h1><tt>{{name}}</tt></h1>
+{{{description}}}
+
+<WIKI:SOURCE style="display:block;">
+{{{example}}}
+</WIKI:SOURCE>
\ No newline at end of file
diff --git a/docs/spec/collectSpec.js b/docs/spec/collectSpec.js
new file mode 100644
index 00000000..2d1b559c
--- /dev/null
+++ b/docs/spec/collectSpec.js
@@ -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;
+}
diff --git a/docs/specs.js b/docs/specs.js
new file mode 100644
index 00000000..5f1cd153
--- /dev/null
+++ b/docs/specs.js
@@ -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);
\ No newline at end of file
diff --git a/docs/widget.template b/docs/widget.template
new file mode 100644
index 00000000..cf82eac9
--- /dev/null
+++ b/docs/widget.template
@@ -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>
\ No newline at end of file
-- 
cgit v1.2.3