add @this and @exampleDescription tags

(also removed markdownNoP, now done through CSS)

4 files changed, 133 insertions, 96 deletions

diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js
index 4abaf0c4..7d024cb5 100644
--- a/docs/spec/ngdocSpec.js
+++ b/docs/spec/ngdocSpec.js
@@ -3,6 +3,18 @@ var DOM = require('dom.js').DOM;
 
 describe('ngdoc', function(){
   var Doc = ngdoc.Doc;
+  var dom;
+
+  beforeEach(function(){
+    dom = new DOM();
+    this.addMatchers({
+      toContain: function(text) {
+        this.actual = this.actual.toString();
+        return this.actual.indexOf(text) > -1;
+      }
+    });
+  });
+
   describe('Doc', function(){
     describe('metadata', function(){
 
@@ -28,9 +40,9 @@ describe('ngdoc', function(){
             '@param {Class=} [c=2] long\nline');
         doc.parse();
         expect(doc.param).toEqual([
-           {name:'a', description:'short', type:'*', optional:false, 'default':undefined},
-           {name:'b', description:'med', type:'Type', optional:false, 'default':undefined},
-           {name:'c', description:'long\nline', type:'Class', optional:true, 'default':'2'}
+           {name:'a', description:'<p>short</p>', type:'*', optional:false, 'default':undefined},
+           {name:'b', description:'<p>med</p>', type:'Type', optional:false, 'default':undefined},
+           {name:'c', description:'<p>long\nline</p>', type:'Class', optional:true, 'default':'2'}
          ]);
       });
 
@@ -39,7 +51,7 @@ describe('ngdoc', function(){
         doc.parse();
         expect(doc.returns).toEqual({
           type: 'Type',
-          description: 'text <em>bold</em>.'
+          description: '<p>text <em>bold</em>.</p>'
         });
       });
 
@@ -118,7 +130,7 @@ describe('ngdoc', function(){
           name : 'number',
           optional: false,
           'default' : undefined,
-          description : 'Number \n to format.' }]);
+          description : '<p>Number \n to format.</p>' }]);
       });
 
       it('should parse with default and optional', function(){
@@ -129,7 +141,7 @@ describe('ngdoc', function(){
           name : 'fractionSize',
           optional: true,
           'default' : '2',
-          description : 'desc' }]);
+          description : '<p>desc</p>' }]);
       });
     });
 
@@ -187,20 +199,20 @@ describe('ngdoc', function(){
       it('should parse @returns with type and description', function() {
         var doc = new Doc("@returns {string} descrip tion");
         doc.parse();
-        expect(doc.returns).toEqual({type: 'string', description: 'descrip tion'});
+        expect(doc.returns).toEqual({type: 'string', description: '<p>descrip tion</p>'});
       });
 
       it('should transform description of @returns with markdown', function() {
         var doc = new Doc("@returns {string} descrip *tion*");
         doc.parse();
-        expect(doc.returns).toEqual({type: 'string', description: 'descrip <em>tion</em>'});
+        expect(doc.returns).toEqual({type: 'string', description: '<p>descrip <em>tion</em></p>'});
       });
 
       it('should support multiline content', function() {
         var doc = new Doc("@returns {string} description\n new line\n another line");
         doc.parse();
         expect(doc.returns).
-          toEqual({type: 'string', description: 'description\n new line\n another line'});
+          toEqual({type: 'string', description: '<p>description\n new line\n another line</p>'});
       });
     });
 
@@ -253,6 +265,22 @@ describe('ngdoc', function(){
       });
     });
 
+    describe('@exampleDescription', function(){
+      it('should render example description', function(){
+        var doc = new Doc('@exampleDescription some\n text');
+        doc.ngdoc = "filter";
+        doc.parse();
+        expect(doc.html()).toContain('<p>some\n text');
+      });
+
+      it('should alias @exampleDescription to @exampleDesc', function(){
+        var doc = new Doc('@exampleDesc some\n text');
+        doc.ngdoc = "filter";
+        doc.parse();
+        expect(doc.html()).toContain('<p>some\n text');
+      });
+    });
+
     describe('@deprecated', function() {
       it('should parse @deprecated', function() {
         var doc = new Doc('@deprecated Replaced with foo.');
@@ -260,21 +288,18 @@ describe('ngdoc', function(){
         expect(doc.deprecated).toBe('Replaced with foo.');
       });
     });
-  });
 
-  describe('usage', function(){
-    var dom;
-
-    beforeEach(function(){
-      dom = new DOM();
-      this.addMatchers({
-        toContain: function(text) {
-          this.actual = this.actual.toString();
-          return this.actual.indexOf(text) > -1;
-        }
+    describe('@this', function(){
+      it('should render @this', function() {
+        var doc = new Doc('@this I am self.');
+        doc.ngdoc = 'filter';
+        doc.parse();
+        expect(doc.html()).toContain('<h3>Method\'s <code>this</code></h3>\n<p>I am self.</p>');
       });
     });
+  });
 
+  describe('usage', function(){
     describe('filter', function(){
       it('should format', function(){
         var doc = new Doc({
diff --git a/docs/src/dom.js b/docs/src/dom.js
index e6dd09e6..d7c2a157 100644
--- a/docs/src/dom.js
+++ b/docs/src/dom.js
@@ -16,11 +16,11 @@ var INLINE_TAGS = {
     b: true
 };
 
-DOM.prototype = { 
+DOM.prototype = {
   toString: function() {
     return this.out.join('');
   },
-  
+
   text: function(content) {
     if (typeof content == "string") {
       this.out.push(content.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'));
@@ -51,19 +51,21 @@ DOM.prototype = {
     this.out.push('>');
     this.text(text);
     this.out.push('</' + name + '>');
-    if (!INLINE_TAGS[name]) 
+    if (!INLINE_TAGS[name])
       this.out.push('\n');
   },
-  
+
   code: function(text) {
     this.tag('div', {'ng:non-bindable':''}, function(){
       this.tag('pre', {'class':"brush: js; html-script: true;"}, text);
     });
   },
-  
-  example: function(source, scenario) {
-    if (source || scenario) {
+
+  example: function(description, source, scenario) {
+    if (description || source || scenario) {
       this.h('Example', function(){
+        if (description)
+          this.html(description);
         if (scenario === false) {
           this.code(source);
         } else {
@@ -75,37 +77,38 @@ DOM.prototype = {
       });
     }
   },
-  
+
   h: function(heading, content, fn){
     if (content==undefined || content && content.legth == 0) return;
     this.tag('h' + this.headingDepth, heading);
     this.headingDepth++;
+    var className = {'class': heading.toLowerCase()};
     if (content instanceof Array) {
-      this.ul(content, {'class': heading.toLowerCase()}, fn);
+      this.ul(content, className, fn);
     } else if (fn) {
-      fn.call(this, content);
+      this.tag('div', className, fn);
     } else {
-      this.text(content);
-    } 
+      this.tag('div', className, content);
+    }
     this.headingDepth--;
   },
-  
+
   h1: function(attr, text) {
     this.tag('h1', attr, text);
   },
-  
+
   h2: function(attr, text) {
     this.tag('h2', attr, text);
   },
-  
+
   h3: function(attr, text) {
     this.tag('h3', attr, text);
   },
-  
+
   p: function(attr, text) {
     this.tag('p', attr, text);
   },
-  
+
   ul: function(list, attr, fn) {
     if (typeof attr == 'function') {
       fn = attr;
@@ -119,5 +122,5 @@ DOM.prototype = {
       });
     });
   }
-  
-};
\ No newline at end of file
+
+};
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 038dda06..8481f7dc 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -7,7 +7,6 @@ var DOM = require('dom.js').DOM;
 var NEW_LINE = /\n\r?/;
 
 exports.markdown = markdown;
-exports.markdownNoP = markdownNoP;
 exports.trim = trim;
 exports.metadata = metadata;
 exports.scenarios = scenarios;
@@ -52,7 +51,7 @@ Doc.prototype = {
     words.sort();
     return words.join(' ');
   },
-  
+
   parse: function(){
     var atName;
     var atText;
@@ -75,7 +74,9 @@ Doc.prototype = {
     flush();
     this.shortName = (this.name || '').split(/[\.#]/).pop();
     this.description = markdown(this.description);
-    
+    this['this'] = markdown(this['this']);
+    this.exampleDescription = markdown(this.exampleDescription || this.exampleDesc);
+
     function flush(){
       if (atName) {
         var text = trim(atText.join('\n'));
@@ -87,7 +88,7 @@ Doc.prototype = {
           }
           var param = {
             name: match[5] || match[4],
-            description:markdownNoP(text.replace(match[0], match[7])),
+            description:markdown(text.replace(match[0], match[7])),
             type: match[1],
             optional: !!match[2],
             'default':match[6]
@@ -101,7 +102,7 @@ Doc.prototype = {
           }
           self.returns = {
             type: match[1],
-            description: markdownNoP(text.replace(match[0], match[2]))
+            description: markdown(text.replace(match[0], match[2]))
           };
         } else if(atName == 'requires') {
           self.requires = self.requires || [];
@@ -124,20 +125,20 @@ Doc.prototype = {
       }
     }
   },
-  
+
   html: function(){
     var dom = new DOM(),
         self = this;
-    
+
     dom.h(this.name, function(){
-      notice('workInProgress', 'Work in Progress', 
+      notice('workInProgress', 'Work in Progress',
           'This page is currently being revised. It might be incomplete or contain inaccuracies.');
       notice('depricated', 'Depricated API');
       dom.h('Description', self.description, html);
       dom.h('Dependencies', self.requires);
-      
+
       usage();
-      
+
       dom.h('Methods', self.methods, function(method){
         var signature = (method.param || []).map(property('name'));
         dom.h(method.shortName + '(' + signature.join(', ') + ')', method, function(){
@@ -148,28 +149,28 @@ Doc.prototype = {
       });
       dom.h('Properties', self.properties, function(property){
         dom.h(property.name, function(){
-         dom.text(property.description); 
+         dom.text(property.description);
          dom.example(property.example, false);
         });
       });
-      
-      dom.example(self.example, self.scenario);
+
+      dom.example(self.exampleDescription, self.example, self.scenario);
     });
-    
+
     return dom.toString();
-    
+
     //////////////////////////
-    
+
     function html(text){
       this.html(text);
     }
-    
+
     function usage(){
       (self['html_usage_' + self.ngdoc] || function(){
         throw new Error("Don't know how to format @ngdoc: " + self.ngdoc);
       }).call(self, dom);
     }
-    
+
     function section(name, property, fn) {
       var value = self[property];
       if (value) {
@@ -182,7 +183,7 @@ Doc.prototype = {
         }
       }
     }
-    
+
     function notice(name, legend, msg){
       if (self[name] == undefined) return;
       dom.tag('fieldset', {'class':name}, function(dom){
@@ -190,9 +191,9 @@ Doc.prototype = {
         dom.text(msg);
       });
     }
-    
+
   },
-  
+
   html_usage_parameters: function(dom) {
     dom.h('Parameters', this.param, function(param){
       dom.tag('code', function(){
@@ -213,7 +214,7 @@ Doc.prototype = {
       dom.html(param.description);
     });
   },
-  
+
   html_usage_returns: function(dom) {
     var self = this;
     if (self.returns) {
@@ -224,7 +225,18 @@ Doc.prototype = {
       });
     }
   },
-  
+
+  html_usage_this: function(dom) {
+    var self = this;
+    if (self['this']) {
+      dom.h(function(dom){
+        dom.html("Method's <code>this</code>");
+      }, function(dom){
+        dom.html(self['this']);
+      });
+    }
+  },
+
   html_usage_function: function(dom){
     var self = this;
     dom.h('Usage', function(){
@@ -234,12 +246,13 @@ Doc.prototype = {
         self.parameters(dom, ', ');
         dom.text(');');
       });
-      
+
       self.html_usage_parameters(dom);
+      self.html_usage_this(dom);
       self.html_usage_returns(dom);
     });
   },
-    
+
   html_usage_directive: function(dom){
     var self = this;
     dom.h('Usage', function(){
@@ -255,7 +268,7 @@ Doc.prototype = {
       self.html_usage_parameters(dom);
     });
   },
-    
+
   html_usage_filter: function(dom){
     var self = this;
     dom.h('Usage', function(){
@@ -269,7 +282,7 @@ Doc.prototype = {
           dom.text(' }}');
         });
       });
-      
+
       dom.h('In JavaScript', function(){
         dom.tag('code', function(){
           dom.text('angular.filter.');
@@ -279,12 +292,13 @@ Doc.prototype = {
           dom.text(')');
         });
       });
-      
+
       self.html_usage_parameters(dom);
+      self.html_usage_this(dom);
       self.html_usage_returns(dom);
     });
   },
-  
+
   html_usage_formatter: function(dom){
     var self = this;
     dom.h('Usage', function(){
@@ -300,7 +314,7 @@ Doc.prototype = {
           dom.text('">');
         });
       });
-      
+
       dom.h('In JavaScript', function(){
         dom.code(function(){
           dom.text('var userInputString = angular.formatter.');
@@ -316,9 +330,10 @@ Doc.prototype = {
           dom.text(');');
         });
       });
-      
+
       self.html_usage_parameters(dom);
-      self.html_usage_returns(dom);  
+      self.html_usage_this(dom);
+      self.html_usage_returns(dom);
     });
   },
 
@@ -333,7 +348,7 @@ Doc.prototype = {
           dom.text('"/>');
         });
       });
-      
+
       dom.h('In JavaScript', function(){
         dom.code(function(){
           dom.text('angular.validator.');
@@ -343,12 +358,13 @@ Doc.prototype = {
           dom.text(')');
         });
       });
-      
+
       self.html_usage_parameters(dom);
+      self.html_usage_this(dom);
       self.html_usage_returns(dom);
     });
   },
-  
+
   html_usage_widget: function(dom){
     var self = this;
     dom.h('Usage', function(){
@@ -383,15 +399,15 @@ Doc.prototype = {
           }
         });
       });
-      
+
       self.html_usage_parameters(dom);
       self.html_usage_returns(dom);
     });
   },
-    
+
   html_usage_overview: function(dom){
   },
-    
+
   html_usage_service: function(dom){
   },
 
@@ -408,7 +424,7 @@ Doc.prototype = {
       sep = separator;
     });
   }
-    
+
 };
 //////////////////////////////////////////////////////////
 
@@ -442,14 +458,6 @@ function markdown (text) {
 };
 var R_LINK = /{@link ([^\s}]+)((\s|\n)+(.+?))?\s*}/m;
             //       1       123     3 4     42
-function markdownNoP(text) {
-  var lines = markdown(text).split(NEW_LINE);
-  var last = lines.length - 1;
-  lines[0] = lines[0].replace(/^<p>/, '');
-  lines[last] = lines[last].replace(/<\/p>$/, '');
-  return lines.join('\n');
-}
-
 
 //////////////////////////////////////////////////////////
 function scenarios(docs){
@@ -525,7 +533,7 @@ function trim(text) {
     lines.pop();
   }
   return lines.join('\n');
-  
+
   function indent(line) {
     for(var i = 0; i < line.length; i++) {
       if (line.charAt(i) != ' ')  {
@@ -550,23 +558,23 @@ function merge(docs){
       i++;
     }
   }
-  
+
   function findParent(doc, name){
     var parentName = doc[name+'Of'];
     if (!parentName) return false;
-    
+
     var parent = byName[parentName];
-    if (!parent) 
-      throw new Error("No parent named '" + parentName + "' for '" + 
+    if (!parent)
+      throw new Error("No parent named '" + parentName + "' for '" +
           doc.name + "' in @" + name + "Of.");
-    
+
     var listName = (name + 's').replace(/ys$/, 'ies');
     var list = parent[listName] = (parent[listName] || []);
     list.push(doc);
     list.sort(orderByName);
     return true;
   }
-  
+
   function orderByName(a, b){
     return a.name < b.name ? -1 : (a.name > b.name ? 1 : 0);
   }
@@ -574,7 +582,7 @@ function merge(docs){
 //////////////////////////////////////////////////////////
 
 function property(name) {
-  return function(value){ 
+  return function(value){
     return value[name];
   };
-} 
\ No newline at end of file
+}
diff --git a/docs/src/templates/docs.css b/docs/src/templates/docs.css
index 3b2dbae6..a687ce87 100644
--- a/docs/src/templates/docs.css
+++ b/docs/src/templates/docs.css
@@ -123,7 +123,8 @@ a {
   border-bottom: 1px solid #888;
 }
 
-#main li > p {
+#main li > p,
+#main div.returns > p {
   display: inline; /* the top most paragraph should not cause new lines inside lists. */
 }