From c2f2587a79aeb77aad66f081cf924a79348a698e Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Wed, 19 Jan 2011 15:42:11 -0800
Subject: fixed example rendering, add tests for it.

---
 docs/angular.formatter.ngdoc                       | 16 +++++++--------
 docs/angular.service.ngdoc                         | 10 ++++-----
 docs/angular.validator.ngdoc                       | 18 ++++++++--------
 docs/angular.widget.ngdoc                          | 18 ++++++++--------
 docs/service.template                              |  2 +-
 docs/spec/domSpec.js                               | 24 ++++++++++++++++++++++
 docs/spec/ngdocSpec.js                             | 10 +++++++++
 docs/spec/writerSpec.js                            |  8 ++++----
 docs/src/gen-docs.js                               |  2 +-
 docs/src/ngdoc.js                                  |  5 +++--
 docs/src/reader.js                                 |  2 +-
 docs/src/templates/doc_widgets.css                 |  2 +-
 docs/src/templates/doc_widgets.js                  | 16 +++++++--------
 docs/src/templates/docs-scenario.html              |  2 +-
 docs/src/templates/docs.js                         |  8 ++++----
 .../templates/syntaxhighlighter/shBrushJScript.js  |  6 +++---
 docs/src/templates/syntaxhighlighter/shBrushXml.js | 10 ++++-----
 docs/src/templates/syntaxhighlighter/shCore.css    |  2 +-
 docs/src/templates/syntaxhighlighter/shCore.js     |  2 +-
 .../templates/syntaxhighlighter/shThemeDefault.css |  2 +-
 docs/src/writer.js                                 | 12 +++++------
 21 files changed, 106 insertions(+), 71 deletions(-)
 create mode 100644 docs/spec/domSpec.js

(limited to 'docs')

diff --git a/docs/angular.formatter.ngdoc b/docs/angular.formatter.ngdoc
index ba28471f..2f4433cf 100644
--- a/docs/angular.formatter.ngdoc
+++ b/docs/angular.formatter.ngdoc
@@ -8,13 +8,13 @@ The formatters are responsible for translating user readable text in an input wi
 data model stored in an application.
 
 # Writting your own Formatter
-Writing your own formatter is easy. Just register a pair of JavaScript functions with 
-`angular.formatter`. One function for parsing user input text to the stored form, 
+Writing your own formatter is easy. Just register a pair of JavaScript functions with
+`angular.formatter`. One function for parsing user input text to the stored form,
 and one for formatting the stored data to user-visible text.
 
-Here is an example of a "reverse" formatter: The data is stored in uppercase and in 
-reverse, while it is displayed in lower case and non-reversed. User edits are 
-automatically parsed into the internal form and data changes are automatically 
+Here is an example of a "reverse" formatter: The data is stored in uppercase and in
+reverse, while it is displayed in lower case and non-reversed. User edits are
+automatically parsed into the internal form and data changes are automatically
 formatted to the viewed form.
 
 <pre>
@@ -56,11 +56,11 @@ angular.formatter('reverse', {
 });
 </script>
 
-Formatted: 
+Formatted:
 <input type="text" name="data" value="angular" ng:format="reverse"/>
 <br/>
 
-Stored: 
+Stored:
 <input type="text" name="data"/><br/>
 <pre>{{data}}</pre>
 
@@ -69,7 +69,7 @@ Stored:
 it('should store reverse', function(){
  expect(element('.doc-example input:first').val()).toEqual('angular');
  expect(element('.doc-example input:last').val()).toEqual('RALUGNA');
- 
+
  this.addFutureAction('change to XYZ', function($window, $document, done){
    $document.elements('.doc-example input:last').val('XYZ').trigger('change');
    done();
diff --git a/docs/angular.service.ngdoc b/docs/angular.service.ngdoc
index a34142bb..4e4810f9 100644
--- a/docs/angular.service.ngdoc
+++ b/docs/angular.service.ngdoc
@@ -76,7 +76,7 @@ window alert.
          };
        }, {$inject: ['$window']});
 </pre>
- 
+
 And here is a unit test for this service. We use Jasmine spy (mock) instead of real browser's alert.
 <pre>
 var mock, notify;
@@ -85,7 +85,7 @@ beforeEach(function() {
   mock = {alert: jasmine.createSpy()};
   notify = angular.service('notify')(mock);
 });
- 
+
 it('should not alert first two notifications', function() {
   notify('one');
   notify('two');
@@ -134,7 +134,7 @@ function myController($loc, $log) {
   };
 }
 // which services to inject ?
-myController.$inject = ['$location', '$log']; 
+myController.$inject = ['$location', '$log'];
 </pre>
 
 @example
@@ -149,13 +149,13 @@ myController.$inject = ['$location', '$log'];
      }
    };
  }, {$inject: ['$window']});
- 
+
  function myController(notifyService) {
    this.callNotify = function(msg) {
      notifyService(msg);
    };
  }
- 
+
  myController.$inject = ['notify'];
 </script>
 
diff --git a/docs/angular.validator.ngdoc b/docs/angular.validator.ngdoc
index acd3caf2..fccdc5a0 100644
--- a/docs/angular.validator.ngdoc
+++ b/docs/angular.validator.ngdoc
@@ -4,7 +4,7 @@
 @namespace Namespace for all filters.
 @description
 # Overview
-Validators are a standard way to check the user input against a specific criteria. For 
+Validators are a standard way to check the user input against a specific criteria. For
 example, you might need to check that an input field contains a well-formed phone number.
 
 # Syntax
@@ -29,10 +29,10 @@ Attach a validator on user input widgets using the `ng:validate` attribute.
 
 
 # Writing your own Validators
-Writing your own validator is easy. To make a function available as a 
-validator, just define the JavaScript function on the `angular.validator` 
-object. <angular/> passes in the input to validate as the first argument 
-to your function. Any additional validator arguments are passed in as 
+Writing your own validator is easy. To make a function available as a
+validator, just define the JavaScript function on the `angular.validator`
+object. <angular/> passes in the input to validate as the first argument
+to your function. Any additional validator arguments are passed in as
 additional arguments to your function.
 
 You can use these variables in the function:
@@ -40,9 +40,9 @@ You can use these variables in the function:
 * `this` — The current scope.
 * `this.$element` — The DOM element containing the binding. This allows the filter to manipulate
   the DOM in addition to transforming the input.
-  
-In this example we have written a upsTrackingNo validator. 
-It marks the input text "valid" only when the user enters a well-formed 
+
+In this example we have written a upsTrackingNo validator.
+It marks the input text "valid" only when the user enters a well-formed
 UPS tracking number.
 
 @css ng-validation-error
@@ -57,7 +57,7 @@ UPS tracking number.
  });
 </script>
 <input type="text" name="trackNo" size="40"
-      ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'" 
+      ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'"
       value="1Z 123 456 78 9012 345 6"/>
 
 @scenario
diff --git a/docs/angular.widget.ngdoc b/docs/angular.widget.ngdoc
index 5f15398f..5942d933 100644
--- a/docs/angular.widget.ngdoc
+++ b/docs/angular.widget.ngdoc
@@ -4,19 +4,19 @@
 @namespace Namespace for all widgets.
 @description
 # Overview
-Widgets allow you to create DOM elements that the browser doesn't 
-already understand. You create the widget in your namespace and 
-assign it behavior. You can only bind one widget per DOM element 
-(unlike directives, in which you can use any number per DOM 
-element). Widgets are expected to manipulate the DOM tree by 
+Widgets allow you to create DOM elements that the browser doesn't
+already understand. You create the widget in your namespace and
+assign it behavior. You can only bind one widget per DOM element
+(unlike directives, in which you can use any number per DOM
+element). Widgets are expected to manipulate the DOM tree by
 adding new elements whereas directives are expected to only modify
 element properties.
 
 Widgets come in two flavors: element and attribute.
 
 # Element Widget
-Let's say we would like to create a new element type in the 
-namespace `my` that can watch an expression and alert() the user 
+Let's say we would like to create a new element type in the
+namespace `my` that can watch an expression and alert() the user
 with each new value.
 
 <pre>
@@ -38,7 +38,7 @@ angular.widget('my:watch', function(compileElement) {
 </pre>
 
 # Attribute Widget
-Let's implement the same widget, but this time as an attribute 
+Let's implement the same widget, but this time as an attribute
 that can be added to any existing DOM element.
 <pre>
 &lt;div my-watch="name"&gt;text&lt;/div&gt;
@@ -70,4 +70,4 @@ angular.widget('@my:watch', function(expression, compileElement) {
   });
 </script>
 <my:time></my:time>
-     
\ No newline at end of file
+
diff --git a/docs/service.template b/docs/service.template
index c28bddc9..639990ed 100644
--- a/docs/service.template
+++ b/docs/service.template
@@ -54,4 +54,4 @@
   </doc:source>
   {{#scenario}}<doc:scenario>{{{scenario}}}</doc:scenario>{{/scenario}}
 </doc:example>
-{{/example}}
\ No newline at end of file
+{{/example}}
diff --git a/docs/spec/domSpec.js b/docs/spec/domSpec.js
new file mode 100644
index 00000000..af1a8faa
--- /dev/null
+++ b/docs/spec/domSpec.js
@@ -0,0 +1,24 @@
+var DOM = require('dom.js').DOM;
+
+describe('dom', function(){
+  describe('example', function(){
+    it('should render code, live, test', function(){
+      var dom = new DOM();
+      dom.example('desc', 'src', 'scenario');
+      expect(dom.toString()).toEqual('<h1>Example</h1>\ndesc<doc:example><doc:source>src</doc:source>\n<doc:scenario>scenario</doc:scenario>\n</doc:example>\n');
+    });
+
+    it('should render non-live, test with description', function(){
+      var dom = new DOM();
+      dom.example('desc', 'src', false);
+      expect(dom.toString()).toEqual('<h1>Example</h1>\ndesc<div ng:non-bindable=""><pre class="brush: js; html-script: true;">src</pre>\n</div>\n');
+    });
+
+    it('should render non-live, test', function(){
+      var dom = new DOM();
+      dom.example('desc', 'src', false);
+      expect(dom.toString()).toContain('<pre class="brush: js; html-script: true;">src</pre>');
+    });
+
+  });
+});
diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js
index 7d024cb5..2bea6e9a 100644
--- a/docs/spec/ngdocSpec.js
+++ b/docs/spec/ngdocSpec.js
@@ -279,6 +279,16 @@ describe('ngdoc', function(){
         doc.parse();
         expect(doc.html()).toContain('<p>some\n text');
       });
+
+      it('should render description in related method', function(){
+        var doc = new Doc();
+        doc.ngdoc = 'service';
+        doc.methods = [new Doc('@ngdoc method\n@exampleDescription MDesc\n@example MExmp').parse()];
+        doc.properties = [new Doc('@ngdoc property\n@exampleDescription PDesc\n@example PExmp').parse()];
+        expect(doc.html()).toContain('<p>MDesc</p><div ng:non-bindable=""><pre class="brush: js; html-script: true;">MExmp</pre>');
+        expect(doc.html()).toContain('<p>PDesc</p><div ng:non-bindable=""><pre class="brush: js; html-script: true;">PExmp</pre>');
+      });
+
     });
 
     describe('@deprecated', function() {
diff --git a/docs/spec/writerSpec.js b/docs/spec/writerSpec.js
index 1a722ca6..8354ad5d 100644
--- a/docs/spec/writerSpec.js
+++ b/docs/spec/writerSpec.js
@@ -2,17 +2,17 @@ var writer = require('writer.js');
 describe('writer', function(){
   describe('toString', function(){
     var toString = writer.toString;
-    
+
     it('should merge string', function(){
       expect(toString('abc')).toEqual('abc');
     });
-    
+
     it('should merge obj', function(){
       expect(toString({a:1})).toEqual('{"a":1}');
     });
-    
+
     it('should merge array', function(){
       expect(toString(['abc',{}])).toEqual('abc{}');
     });
   });
-});
\ No newline at end of file
+});
diff --git a/docs/src/gen-docs.js b/docs/src/gen-docs.js
index 0dee586b..1c03a0f1 100644
--- a/docs/src/gen-docs.js
+++ b/docs/src/gen-docs.js
@@ -38,7 +38,7 @@ var writes = callback.chain(function(){
   writer.copy('jquery.min.js', writes.waitFor());
 });
 writes.onDone(function(){
-  console.log('DONE. Generated ' + docs.length + ' pages in ' + 
+  console.log('DONE. Generated ' + docs.length + ' pages in ' +
       (now()-start) + 'ms.' );
 });
 work.onDone(writes);
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 8481f7dc..daa44fef 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -76,6 +76,7 @@ Doc.prototype = {
     this.description = markdown(this.description);
     this['this'] = markdown(this['this']);
     this.exampleDescription = markdown(this.exampleDescription || this.exampleDesc);
+    return this;
 
     function flush(){
       if (atName) {
@@ -144,13 +145,13 @@ Doc.prototype = {
         dom.h(method.shortName + '(' + signature.join(', ') + ')', method, function(){
           dom.html(method.description);
           method.html_usage_parameters(dom);
-          dom.example(method.example, false);
+          dom.example(method.exampleDescription, method.example, false);
         });
       });
       dom.h('Properties', self.properties, function(property){
         dom.h(property.name, function(){
          dom.text(property.description);
-         dom.example(property.example, false);
+         dom.example(property.exampleDescription, property.example, false);
         });
       });
 
diff --git a/docs/src/reader.js b/docs/src/reader.js
index 8f9f22c3..5a653cd6 100644
--- a/docs/src/reader.js
+++ b/docs/src/reader.js
@@ -88,4 +88,4 @@ function findNgDocInJsFile(file, callback) {
 
 
 
-exports.collect = collect;
\ No newline at end of file
+exports.collect = collect;
diff --git a/docs/src/templates/doc_widgets.css b/docs/src/templates/doc_widgets.css
index 8361f105..9f007f0e 100644
--- a/docs/src/templates/doc_widgets.css
+++ b/docs/src/templates/doc_widgets.css
@@ -32,4 +32,4 @@ li.doc-example-live {
 
 div.syntaxhighlighter {
   padding-bottom: 1px !important; /* fix to remove unnecessary scrollbars http://is.gd/gSMgC */
-}
\ No newline at end of file
+}
diff --git a/docs/src/templates/doc_widgets.js b/docs/src/templates/doc_widgets.js
index 18aeeacb..2d1ab8c6 100644
--- a/docs/src/templates/doc_widgets.js
+++ b/docs/src/templates/doc_widgets.js
@@ -1,5 +1,5 @@
 (function(){
-  
+
   var angularJsUrl;
   var scripts = document.getElementsByTagName("script");
   var filename = /(.*\/)angular([^\/]*)/;
@@ -10,7 +10,7 @@
     }
   }
 
-  
+
   var HTML_TEMPLATE =
   '<!doctype html>\n' +
   '<html xmlns:ng="http://angularjs.org">\n' +
@@ -32,15 +32,15 @@
     var tabs = angular.element(
         '<ul class="doc-example">' +
           '<li class="doc-example-heading"><h3>Source</h3></li>' +
-          '<li class="doc-example-source" ng:non-bindable>' + 
-            '<pre class="brush: js; html-script: true; highlight: [' + 
+          '<li class="doc-example-source" ng:non-bindable>' +
+            '<pre class="brush: js; html-script: true; highlight: [' +
             code.hilite + ']; toolbar: false;"></pre></li>' +
           '<li class="doc-example-heading"><h3>Live Preview</h3></li>' +
           '<li class="doc-example-live">' + exampleSrc +'</li>' +
           '<li class="doc-example-heading"><h3>Scenario Test</h3></li>' +
           '<li class="doc-example-scenario"><pre class="brush: js">' + scenario.text() + '</pre></li>' +
         '</ul>');
-    
+
     tabs.find('li.doc-example-source > pre').text(HTML_TEMPLATE.replace('_HTML_SOURCE_', code.html));
 
     element.html('');
@@ -54,7 +54,7 @@
       alert(e);
     }
   });
-  
+
   function indent(text) {
     var lines = text.split(/\n/);
     var lineNo = [];
@@ -66,5 +66,5 @@
     }
     return {html: lines.join('\n'), hilite: lineNo.join(',') };
   };
-  
-})();
\ No newline at end of file
+
+})();
diff --git a/docs/src/templates/docs-scenario.html b/docs/src/templates/docs-scenario.html
index c75155c5..bc244d5d 100644
--- a/docs/src/templates/docs-scenario.html
+++ b/docs/src/templates/docs-scenario.html
@@ -7,4 +7,4 @@
 </head>
 <body>
 </body>
-</html>
\ No newline at end of file
+</html>
diff --git a/docs/src/templates/docs.js b/docs/src/templates/docs.js
index 6bf86ed3..f1cfc3e7 100644
--- a/docs/src/templates/docs.js
+++ b/docs/src/templates/docs.js
@@ -2,7 +2,7 @@ DocsController.$inject = ['$location', '$browser', '$window'];
 function DocsController($location, $browser, $window) {
   this.pages = NG_PAGES;
   window.$root = this.$root;
-  
+
   this.getUrl = function(page){
     return '#!' + page.name;
   };
@@ -10,7 +10,7 @@ function DocsController($location, $browser, $window) {
   this.getCurrentPartial = function(){
     return './' + this.getTitle() + '.html';
   };
-  
+
   this.getTitle = function(){
     var hashPath = $location.hashPath || '!angular';
     if (hashPath.match(/^!angular/)) {
@@ -18,7 +18,7 @@ function DocsController($location, $browser, $window) {
     }
     return this.partialTitle;
   };
-  
+
   this.getClass = function(page) {
     var depth = page.name.split(/\./).length - 1,
         cssClass = 'level-' + depth + (page.name == this.getTitle() ? ' selected' : '');
@@ -37,7 +37,7 @@ function DocsController($location, $browser, $window) {
            "subject=" + escape("Feedback on " + $location.href) + "&" +
            "body=" + escape("Hi there,\n\nI read " + $location.href + " and wanted to ask ....");
   };
-  
+
 }
 
 angular.filter('short', function(name){
diff --git a/docs/src/templates/syntaxhighlighter/shBrushJScript.js b/docs/src/templates/syntaxhighlighter/shBrushJScript.js
index ff98daba..d52a77b2 100644
--- a/docs/src/templates/syntaxhighlighter/shBrushJScript.js
+++ b/docs/src/templates/syntaxhighlighter/shBrushJScript.js
@@ -7,7 +7,7 @@
  *
  * @version
  * 3.0.83 (July 02 2010)
- * 
+ *
  * @copyright
  * Copyright (C) 2004-2010 Alex Gorbatchev.
  *
@@ -29,7 +29,7 @@
 						;
 
 		var r = SyntaxHighlighter.regexLib;
-		
+
 		this.regexList = [
 			{ regex: r.multiLineDoubleQuotedString,					css: 'string' },			// double quoted strings
 			{ regex: r.multiLineSingleQuotedString,					css: 'string' },			// single quoted strings
@@ -38,7 +38,7 @@
 			{ regex: /\s*#.*/gm,									css: 'preprocessor' },		// preprocessor tags like #region and #endregion
 			{ regex: new RegExp(this.getKeywords(keywords), 'gm'),	css: 'keyword' }			// keywords
 			];
-	
+
 		this.forHtmlScript(r.scriptScriptTags);
 	};
 
diff --git a/docs/src/templates/syntaxhighlighter/shBrushXml.js b/docs/src/templates/syntaxhighlighter/shBrushXml.js
index 69d9fd0b..ac879949 100644
--- a/docs/src/templates/syntaxhighlighter/shBrushXml.js
+++ b/docs/src/templates/syntaxhighlighter/shBrushXml.js
@@ -7,7 +7,7 @@
  *
  * @version
  * 3.0.83 (July 02 2010)
- * 
+ *
  * @copyright
  * Copyright (C) 2004-2010 Alex Gorbatchev.
  *
@@ -28,8 +28,8 @@
 				tag = new XRegExp('(&lt;|<)[\\s\\/\\?]*(?<name>[:\\w-\\.]+)', 'xg').exec(code),
 				result = []
 				;
-		
-			if (match.attributes != null) 
+
+			if (match.attributes != null)
 			{
 				var attributes,
 					regex = new XRegExp('(?<name> [\\w:\\-\\.]+)' +
@@ -37,7 +37,7 @@
 										'(?<value> ".*?"|\'.*?\'|\\w+)',
 										'xg');
 
-				while ((attributes = regex.exec(code)) != null) 
+				while ((attributes = regex.exec(code)) != null)
 				{
 					result.push(new constructor(attributes.name, match.index + attributes.index, 'color1'));
 					result.push(new constructor(attributes.value, match.index + attributes.index + attributes[0].indexOf(attributes.value), 'string'));
@@ -51,7 +51,7 @@
 
 			return result;
 		}
-	
+
 		this.regexList = [
 			{ regex: new XRegExp('(\\&lt;|<)\\!\\[[\\w\\s]*?\\[(.|\\s)*?\\]\\](\\&gt;|>)', 'gm'),			css: 'color2' },	// <![ ... [ ... ]]>
 			{ regex: SyntaxHighlighter.regexLib.xmlComments,												css: 'comments' },	// <!-- ... -->
diff --git a/docs/src/templates/syntaxhighlighter/shCore.css b/docs/src/templates/syntaxhighlighter/shCore.css
index 34f6864a..4f0021e2 100644
--- a/docs/src/templates/syntaxhighlighter/shCore.css
+++ b/docs/src/templates/syntaxhighlighter/shCore.css
@@ -7,7 +7,7 @@
  *
  * @version
  * 3.0.83 (July 02 2010)
- * 
+ *
  * @copyright
  * Copyright (C) 2004-2010 Alex Gorbatchev.
  *
diff --git a/docs/src/templates/syntaxhighlighter/shCore.js b/docs/src/templates/syntaxhighlighter/shCore.js
index b47b6454..effcf59d 100644
--- a/docs/src/templates/syntaxhighlighter/shCore.js
+++ b/docs/src/templates/syntaxhighlighter/shCore.js
@@ -7,7 +7,7 @@
  *
  * @version
  * 3.0.83 (July 02 2010)
- * 
+ *
  * @copyright
  * Copyright (C) 2004-2010 Alex Gorbatchev.
  *
diff --git a/docs/src/templates/syntaxhighlighter/shThemeDefault.css b/docs/src/templates/syntaxhighlighter/shThemeDefault.css
index 13654117..8a870e4e 100644
--- a/docs/src/templates/syntaxhighlighter/shThemeDefault.css
+++ b/docs/src/templates/syntaxhighlighter/shThemeDefault.css
@@ -7,7 +7,7 @@
  *
  * @version
  * 3.0.83 (July 02 2010)
- * 
+ *
  * @copyright
  * Copyright (C) 2004-2010 Alex Gorbatchev.
  *
diff --git a/docs/src/writer.js b/docs/src/writer.js
index eb1b190f..c72a54a4 100644
--- a/docs/src/writer.js
+++ b/docs/src/writer.js
@@ -13,17 +13,17 @@ function output(docs, content, callback){
 exports.output = function(file, content, callback){
   //console.log('writing', OUTPUT_DIR + file, '...');
   fs.writeFile(
-      OUTPUT_DIR + file, 
-      exports.toString(content), 
+      OUTPUT_DIR + file,
+      exports.toString(content),
       callback);
 };
 
 
 exports.toString = function toString(obj){
   switch (typeof obj) {
-  case 'string': 
+  case 'string':
     return obj;
-  case 'object': 
+  case 'object':
     if (obj instanceof Array) {
       obj.forEach(function (value, key){
         obj[key] = toString(value);
@@ -54,8 +54,8 @@ exports.copy = function(filename, callback){
   fs.readFile('docs/src/templates/' + filename, function(err, content){
     if (err) return callback.error(err);
     fs.writeFile(
-        OUTPUT_DIR + filename, 
-        content, 
+        OUTPUT_DIR + filename,
+        content,
         callback);
   });
 };
-- 
cgit v1.2.3