From 70c74a9c4e3f1c3fdeb285e765a03bc878d14422 Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Wed, 19 Jan 2011 12:16:21 -0800
Subject: add @this and @exampleDescription tags (also removed markdownNoP, now
done through CSS)
---
docs/src/dom.js | 41 ++++++++-------
docs/src/ngdoc.js | 120 +++++++++++++++++++++++---------------------
docs/src/templates/docs.css | 3 +-
3 files changed, 88 insertions(+), 76 deletions(-)
(limited to 'docs/src')
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, '&').replace(//g, '>'));
@@ -51,19 +51,21 @@ DOM.prototype = {
this.out.push('>');
this.text(text);
this.out.push('');
- 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 this");
+ }, 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(/^/, '');
- 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. */
}
--
cgit v1.2.3