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

More fixes to schema. Added tests for @tag.

Browse Source
This commit is contained in:
Michael Mathews 2010-08-02 23:27:04 +01:00
parent 80216a5689
commit 931d2ee6bf
9 changed files with 150 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
examples/base.js
View File

@ -10,7 +10,7 @@ var Animal = Class.extend({
/**
* An instance property.
* @property {string} Animal#name
* @property {string|undefined} Animal#name
*/
this.name = name;
},

2
modules/jsdoc/doclet.js
View File

@ -197,7 +197,7 @@
if (tagValue) {
if (typeof o[tagName] === 'undefined') { // not defined
o[tagName] = tagValue;
o[tagName] = tagAbout.forceArray? [tagValue] : tagValue;
}
else if (typeof o[tagName].push === 'function') { // is an array
o[tagName].push(tagValue);

54
modules/jsdoc/schema.js
View File

@ -7,12 +7,12 @@
exports.jsdocSchema = {
"properties": {
"docnode": {
"doc": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": { // unique to each documentation
"path": { // unique identifier for each doc
"type": "string",
"maxItems": 1
},
@ -56,7 +56,7 @@ exports.jsdocSchema = {
"optional": true,
},
"type": { // what type is the value that this doc is associated with, like "number"
"type": "array",
"type": ["string", "array"],
"optional": true,
"items": {
"type": "string"
@ -99,45 +99,45 @@ exports.jsdocSchema = {
}
}
},
"meta": { // information about this documentation
"tag": { // arbitrary tags associated with this doc
"type": "array",
"optional": true,
"items": {
"type": "object",
"properties": {
"name": { // the name of a tag
"type": "string"
},
"desc": { // a value associated with that tag name
"type": "string",
"optional": true
}
}
}
},
"meta": { // information about this doc
"type": "object",
"optional": true,
"maxItems": 1,
"file": { // what is the name of the file this documentation appears in?
"file": { // what is the name of the file this doc appears in?
"type": "string",
"optional": true,
"maxItems": 1
},
"line": { // on what line of the file does this documentation appear?
"line": { // on what line of the file does this doc appear?
"type": "number",
"optional": true,
"maxItems": 1
},
"tags": { // arbitrary tags associated with this documentation
"type": "array",
"optional": true,
"items": {
"type": "object",
"properties": {
"tagname": { // the name of a tag
"type": "string"
},
"tagtext": { // a value associated with that tag name
"type": "string",
"optional": true
}
}
}
}
}
}
}
},
"meta": { // information about the generation for all the documentation
"meta": { // information about the generation for all the docs
"type": "object",
"optional": true,
"maxItems": 1,
"project": { // to what project does this documentation belong
"project": { // to what project does this doc belong
"type": "object",
"optional": true,
"maxItems": 1,
@ -151,17 +151,17 @@ exports.jsdocSchema = {
"format": "uri"
}
},
"generated": { // some information about the running of the documentation generator
"generated": { // some information about the running of the doc generator
"type": "object",
"optional": true,
"maxItems": 1,
"date": { // on what date and time was the documentation generated?
"date": { // on what date and time was the doc generated?
"type": "string",
"maxItems": 1,
"optional": true,
"format": "date-time"
},
"parser": { // what tool was used to generate the documentation
"parser": { // what tool was used to generate the doc
"type": "string",
"maxItems": 1,
"optional": true

12
modules/jsdoc/tagdictionary.js
View File

@ -80,7 +80,8 @@
canHavePdesc : false, // this tag can have a parameter-type desc
keepsWhitespace : false, // don't try to tidy up the whitespace in this tag?
impliesTag : false, // this tag implies another tag
isScalar : false // can only have a single value (first wins)
isScalar : false, // can only have a single value (first wins)
forceArray : false // must always be an array
};
/** Syntax: @access <text> (private|public|protected)
@ -209,7 +210,8 @@
setsDocletKind: true,
setsDocletDesc: true,
setsDocletName: true,
setsDocletDocspace: true
setsDocletDocspace: true,
impliesTag: 'scope global'
});
/** Syntax: @method|function <returnType> <docletName> <docletDesc>
@ -300,7 +302,8 @@
isExported: true,
canHaveType: true,
canHavePname: true,
canHavePdesc: true
canHavePdesc: true,
forceArray: true
});
/** Syntax: @type <type>
@ -474,7 +477,8 @@
new TagDefinition('tag', {
isExported: true,
canHavePname: true,
canHavePdesc: true
canHavePdesc: true,
forceArray: true
});
/** Syntax: @deprecated <text>

2
test/runall.js
View File

@ -25,7 +25,7 @@ load(BASEDIR + '/test/tests/22_tag_preserve.js');
load(BASEDIR + '/test/tests/23_tag_fires.js');
load(BASEDIR + '/test/tests/24_tag_exception.js');
load(BASEDIR + '/test/tests/25_tag_scope.js');
load(BASEDIR + '/test/tests/26_tag_tag.js');
// see http://visionmedia.github.com/jspec/
JSpec.run({

6
test/samples/jsdoc_test.js
View File

@ -298,7 +298,6 @@ Square.prototype.setHeight = function(height){
* @class Circle class is another subclass of Shape
* @extends Shape
* @param {int} radius The optional radius of this {@link Circle }
* @mixin Square.prototype.setWidth as this.setDiameter
*/
function Circle(radius){
if (radius) {
@ -342,6 +341,11 @@ Circle.prototype.setRadius = function(radius){
this.radius = radius;
}
/**
* @name Circle#setDiameter => Square#setWidth
*/
Circle.prototype.setDiameter = Square.prototype.setWidth;
/**
* An example of a class (static) method that acts as a factory for Circle
* objects. Given a radius value, this method creates a new Circle.

15
test/samples/tag_tag.js Normal file
View File

@ -0,0 +1,15 @@
/** @namespace foo
@tag hilited
*/
/** @namespace bar
@tag api developer
*/
/** @namespace baz
@tag support - experimental
@tag api internal
*/
/** @namespace zub
*/

30
test/tests/19_tag_param.js
View File

@ -55,21 +55,23 @@
});
describe('A doclet with one param tag', function() {
it('should have a `param` property that is an object', function() {
it('should have a `param` property that is an array of one object', function() {
var doclet = doclets[2];
expect(doclet).to(have_property, 'param');
expect(doclet.param).to(be_an, Object);
expect(doclet.param).to(be_an, Array);
expect(doclet.param.length).to(be, 1);
expect(doclet.param[0]).to(be_an, Object);
});
});
describe('A doclet with one param tag having a type and a name', function() {
it('should have a `param` property with a `type` and `name`', function() {
it('should have a `param` array with a single member with a `type` and `name`', function() {
var doclet = doclets[2];
expect(doclet).to(have_property, 'param');
expect(doclet.param.type).to(be_an, Array); // types are always arrays
expect(doclet.param.type).to(eql, ['string']);
expect(doclet.param.name).to(be_an, String);
expect(doclet.param.name).to(eql, 'str');
expect(doclet.param[0].type).to(be_an, Array); // types are always arrays
expect(doclet.param[0].type).to(eql, ['string']);
expect(doclet.param[0].name).to(be_an, String);
expect(doclet.param[0].name).to(eql, 'str');
});
it('should not have a `desc`', function() {
@ -79,15 +81,15 @@
});
describe('A doclet with one param tag having a type, name and a desc', function() {
it('should have a `param` property with a `type`, `name` and `desc`', function() {
it('should have a `param` array with a single member with a `type`, `name` and `desc`', function() {
var doclet = doclets[3];
expect(doclet).to(have_property, 'param');
expect(doclet.param.type).to(be_an, Array); // types are always arrays
expect(doclet.param.type).to(eql, ['string']);
expect(doclet.param.name).to(be_an, String);
expect(doclet.param.name).to(eql, 'message');
expect(doclet.param.desc).to(be_an, String);
expect(doclet.param.desc).to(eql, 'the message to encrypt.');
expect(doclet.param[0].type).to(be_an, Array); // types are always arrays
expect(doclet.param[0].type).to(eql, ['string']);
expect(doclet.param[0].name).to(be_an, String);
expect(doclet.param[0].name).to(eql, 'message');
expect(doclet.param[0].desc).to(be_an, String);
expect(doclet.param[0].desc).to(eql, 'the message to encrypt.');
});
});

76
test/tests/26_tag_tag.js Normal file
View File

@ -0,0 +1,76 @@
(function() {
var jsdoc,
doclets;
JSpec.describe('@scope', function() {
before(function() {
// docsets can only be created by parsers
jsdoc = {
tag: require('jsdoc/tag'),
parser: require('jsdoc/parser')
};
jsdoc.parser.parseFiles(BASEDIR + 'test/samples/tag_tag.js');
doclets = jsdoc.parser.result.map(function($){ return $.toObject(); });
});
describe('A doclet with single @tag <name>', function() {
it('should have a `tag` property of type array with a single member', function() {
var doclet = doclets[0];
expect(doclet).to(have_property, 'tag');
expect(doclet.tag).to(be_an, Array);
expect(doclet.tag.length).to(be, 1);
});
it('that tag should have a name property set to <name>, and no description property', function() {
var doclet = doclets[0];
expect(doclet.tag[0]).to(have_property, 'name');
expect(doclet.tag[0].desc).to(be_undefined);
expect(doclet.tag[0].name).to(be_an, String);
expect(doclet.tag[0].name).to(be, 'hilited');
});
});
describe('A doclet with single @tag <name> <desc>', function() {
it('should have a tag with a name property set to <name>, and description set to <desc>', function() {
var doclet = doclets[1];
expect(doclet.tag[0]).to(have_property, 'name');
expect(doclet.tag[0]).to(have_property, 'desc');
expect(doclet.tag[0].name).to(be_an, String);
expect(doclet.tag[0].name).to(be, 'api');
expect(doclet.tag[0].desc).to(be_an, String);
expect(doclet.tag[0].desc).to(be, 'developer');
});
});
describe('A doclet with two @tag <name> <desc>', function() {
it('should have a tag property set to an array of length 2', function() {
var doclet = doclets[2];
expect(doclet).to(have_property, 'tag');
expect(doclet.tag).to(be_an, Array);
expect(doclet.tag.length).to(be, 2);
});
});
describe('A doclet with two @tag <name> - <desc>', function() {
it('should have a tag property with a name property set to <name>, and description set to <desc>', function() {
var doclet = doclets[2];
expect(doclet.tag[0]).to(have_property, 'name');
expect(doclet.tag[0]).to(have_property, 'desc');
expect(doclet.tag[0].name).to(be, 'support');
expect(doclet.tag[0].desc).to(be, 'experimental');
});
});
describe('A doclet with no @tag', function() {
it('should not have a tag property', function() {
var doclet = doclets[3];
expect(doclet.tag).to(be_undefined);
});
});
});
})();