archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

Added support for @project and @license tags. Better support for this-variables in a @constructs scope. Name property no does not have namespace applied, only longname does.

Browse Source
This commit is contained in:
Michael Mathews 2011-01-24 22:42:14 +00:00
parent 221aa8cbad
commit 0297bb99f9
13 changed files with 93 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
modules/jsdoc/name.js
View File

@ -28,11 +28,6 @@
memberof = doclet.memberof || '',
about = {},
parentDoc;
// TODO
// if (currentModule) {
// name = name.replace(/^exports\.(?=.+$)/, currentModule + '.');
// }
name = name? (''+name).replace(/\.prototype\.?/g, '#') : '';
@ -62,7 +57,7 @@
doclet.memberof = about.memberof;
}
if (about.longname) {
if (about.longname && !doclet.longname) {
doclet.longname = about.longname;
}
@ -74,13 +69,11 @@
doclet.scope = puncToScope[about.scope];
}
else {
if (doclet.name && doclet.memberof) {
if (doclet.name && doclet.memberof && !doclet.longname) {
doclet.scope = 'static'; // default scope when none is provided
doclet.longname = doclet.memberof + scopeToPunc[doclet.scope] + doclet.name;
}
}
}
function quoteUnsafe(name, kind) { // docspaced names may have unsafe characters which need to be quoted by us

4
modules/jsdoc/src/parser.js
View File

@ -153,6 +153,10 @@
if (memberof.doclet['this']) {
return memberof.doclet['this'];
}
// like: Foo.constructor = function(n) { /** blah */ this.name = n; }
else if (memberof.doclet.kind === 'function' && memberof.doclet.memberof) {
return memberof.doclet.memberof;
}
// walk up to the closest class we can find
else if (memberof.doclet.kind === 'class' || memberof.doclet.kind === 'module') {
return memberof.doclet.longname||memberof.doclet.name;

25
modules/jsdoc/tag/dictionary/definitions.js
View File

@ -53,7 +53,7 @@
// handle special case where both @class and @constructor tags exist in same doclet
if (tag.originalTitle === 'class') {
if ( /@construct(s|or)\b/i.test(doclet.comment) ) {
doclet.classdesc = tag.value; // treat @class tag as a @classdesc tag instead
doclet.classdesc = tag.value; // treat the @class tag as a @classdesc tag instead
return;
}
}
@ -193,9 +193,7 @@
dictionary.defineTag('instance', {
onTagged: function(doclet, tag) {
setDocletScopeToTitle(doclet, tag);
setDocletScopeToTitle(doclet, tag);
}
});
@ -203,6 +201,13 @@
mustHaveValue: true
});
dictionary.defineTag('license', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
doclet.license = tag.value;
}
});
dictionary.defineTag('alias', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
@ -274,6 +279,15 @@
}
});
dictionary.defineTag('project', {
mustHaveValue: true,
onTagged: function(doclet, tag) {
setDocletKindToTitle(doclet, tag);
setDocletNameToValue(doclet, tag);
applyNamespace(doclet, tag);
}
});
dictionary.defineTag('property', {
onTagged: function(doclet, tag) {
setDocletKindToTitle(doclet, tag);
@ -413,7 +427,8 @@
function applyNamespace(doclet, tag) {
if (!doclet.name) return; // error?
doclet.name = app.jsdoc.name.applyNamespace(doclet.name, tag.title)
//doclet.displayname = doclet.name;
doclet.longname = app.jsdoc.name.applyNamespace(doclet.name, tag.title)
}
function setDocletNameToFilename(doclet, tag) {

5
templates/default/publish.js
View File

@ -85,17 +85,16 @@
var modules = data.get( data.find({kind: 'module'}) );
modules.forEach(function(m) {
m.methods = data.get( data.find({kind: 'function', memberof: m.longname}) );
m.displayName = m.longname.replace(/^module:/, '');
m.hasMethods = (m.methods && m.methods.length > 0);
m.methods.forEach(function(f) {
m.methods.forEach(function(f) {
var pnames = [];
if (f.params) {
f.params.forEach(function(p) {
if (p.name && p.name.indexOf('.') === -1) { pnames.push(p.name); }
});
}
f.synopsis = 'require("'+m.displayName+'").'+f.name+'('+pnames.join(', ')+');'
f.synopsis = 'require("'+m.name+'").'+f.name+'('+pnames.join(', ')+');'
f.hasParams = (f.params && f.params.length > 0);
f.hasReturns = (f.returns && f.returns.length > 0);
});

2
templates/default/tmpl/container.mustache
View File

@ -168,7 +168,7 @@
<h1>{{title}}</h1>
{{#docs}}
<h2 class="symbol-head" id="{{longname}}">{{displayName}}</h2>
<h2 class="symbol-head" id="{{longname}}">{{name}}</h2>
{{#hasMethods}}
<h3>Methods</h3>

4
test/cases/constructstag.js
View File

@ -2,7 +2,7 @@
Describe your class here
@class TextBlock
*/
classify('TextBlock', {
Classify('TextBlock', {
/**
Document your constructor function here.
@ -17,6 +17,6 @@ classify('TextBlock', {
Document your method here.
@memberof TextBlock#
*/
align: function(){
align: function() {
}
});

26
test/cases/constructstag3.js Normal file
View File

@ -0,0 +1,26 @@
/**
A class that represents a person.
@class
*/
var Person = Class.create({
/**
@constructs Person
@param {string} name
*/
initialize: function(name) {
/** The name of the person. */
this.name = name;
},
/**
@memberof Person#
@param {string} message
*/
say: function(message) {
/** The person's message. */
this.message = message;
}
});

9
test/cases/projecttag.js Normal file
View File

@ -0,0 +1,9 @@
/**
An automated documentation generator for JavaScript.
@project JSDoc
@version 3.0.0
@copyright 2011 (c) Michael Mathews <micmath@gmail.com>
@license Apache Version 2 <http://www.apache.org/licenses/LICENSE-2.0>
*/
function blah(url) {
}

1
test/runner.js
View File

@ -95,6 +95,7 @@ testFile('test/t/cases/authortag.js');
testFile('test/t/cases/classtag.js');
testFile('test/t/cases/constructstag.js');
testFile('test/t/cases/constructstag2.js');
testFile('test/t/cases/constructstag3.js');
testFile('test/t/cases/constructortag.js');
testFile('test/t/cases/copyrighttag.js');
testFile('test/t/cases/deprecatedtag.js');

12
test/t/cases/constructstag3.js Normal file
View File

@ -0,0 +1,12 @@
(function() {
var docSet = testhelpers.getDocSetFromFile('test/cases/constructstag3.js'),
personName = docSet.getByLongname('Person#name')[0];
//dump(docSet.doclets); exit(0);
test('When a function symbol has an @constructs tag, any this-variables are ducumented as instance members of the class.', function() {
assert.equal(personName.memberof, 'Person');
assert.equal(personName.scope, 'instance');
});
})();

2
test/t/cases/modules/data/mod-1.js
View File

@ -12,7 +12,7 @@
test('When a module has no name documented, the name comes from the file path.', function() {
assert.ok(doclets.length > 1);
assert.equal(doclets[0].name, 'module:data/mod-1');
assert.equal(doclets[0].longname, 'module:data/mod-1');
});
})();

2
test/t/cases/modules/data/mod-2.js
View File

@ -12,7 +12,7 @@
test('When a module has a name documented, that name is used.', function() {
assert.ok(doclets.length > 1);
assert.equal(doclets[0].name, 'module:my/module/name');
assert.equal(doclets[0].longname, 'module:my/module/name');
});
})();

12
test/t/cases/projecttag.js Normal file
View File

@ -0,0 +1,12 @@
(function() {
var docSet = testhelpers.getDocSetFromFile('test/cases/constructstag3.js'),
personName = docSet.getByLongname('Person#name')[0];
//dump(docSet.doclets); exit(0);
test('When a function symbol has an @constructs tag, any this-variables are ducumented as instance members of the class.', function() {
assert.equal(personName.memberof, 'Person');
assert.equal(personName.scope, 'instance');
});
})();