aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/spec/ngdocSpec.js65
-rw-r--r--docs/src/dom.js41
-rw-r--r--docs/src/ngdoc.js120
-rw-r--r--docs/src/templates/docs.css3
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. */
}
generated by cgit v1.2.3 (git 2.25.1) at 2025-11-01 08:31:48 +0000