alexey.zholtikov/upm
1
0
Fork 0
mirror of https://github.com/eclipse/upm.git synced 2025-03-15 04:57:30 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

jsdoc: change errors to warning when unknown tags are encountered in xml

Browse Source 
Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
Mihai Tudor Panu 2015-05-26 17:22:13 -07:00
parent 33b508110e
commit 54c2c8db76
1 changed files with 38 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
doxy/node/xml2js.js
View File

@ -36,7 +36,7 @@ Promise.promisifyAll(fs);
var xml2js = {
// js-format specs
// MODULE: <module name>
// ENUMS: {
@ -47,7 +47,7 @@ var xml2js = {
// }
// ENUMS_BY_GROUP: {
// <enum type>: {
// description: <enum group description>
// description: <enum group description>
// members: [ <enum name>, ... ]
// }, ...
// }
@ -58,7 +58,7 @@ var xml2js = {
// <param name>: {
// type: <param type>,
// description: <param description >
// }, ...
// }, ...
// },
// return: {
// type: <return type>,
@ -79,7 +79,7 @@ var xml2js = {
// enums: { ... },
// enums_by_group: { ... }
// }, ...
// }
// }
// CLASSGROUPS: {
// <group name>: {
// description: <group description>,
@ -92,23 +92,23 @@ var xml2js = {
METHODS: {},
CLASSES: {},
CLASSGROUPS: {},
// baseline c -> js type mapping
TYPEMAPS: {
'^(const)?\\s*(unsigned|signed)?\\s*(int|short|long|float|double|size_t|u?int\\d{1,2}_t)?$': 'Number',
'^bool$': 'Boolean',
'^(const)?\\s*(unsigned|signed)?\\s*(char|char\\s*\\*|std::string)$': 'String' // TODO: verify that swig does this mapping
},
// custom c -> js type mapping for pointers
// ARRAY_TYPEMAPS: {
// ARRAY_TYPEMAPS: {
// <pointer data type>: {
// arrayType: <swig generated array type that will replace pointers of data type>,
// classes: [ <class that contains arrayType>, ... ]
// }, ...
// }
// }
// POINTER_TYPEMAPS: {
// <class that contains pointerType>: {
// <c pointer data type>: <js swig generated pointer type that will replace pointers of data type>, ...
@ -116,8 +116,8 @@ var xml2js = {
// }
ARRAY_TYPEMAPS: {},
POINTER_TYPEMAPS: {},
// add command line options for this module
addOptions: function(opts) {
xml2js.opts = opts;
@ -128,8 +128,8 @@ var xml2js = {
.option('-g, --imagedir [directory]', 'directory to link to where the images will be kept', '')
.option('-s, --strict', 'leave out methods/variables if unknown type')
},
// parse doxygen xml -> js-format specs
// TODO: figure out whether we need to document any protected methods/variables
parse: function() {
@ -138,9 +138,9 @@ var xml2js = {
var CLASS_SPEC = function(c) { return xml2js.opts.inputdir + '/' + c + '.xml'; }
var TYPES_SPEC = xml2js.opts.inputdir + '/types_8h.xml';
xml2js.MODULE = xml2js.opts.module;
return Promise.join(createXmlParser(XML_GRAMMAR_SPEC),
return Promise.join(createXmlParser(XML_GRAMMAR_SPEC),
xml2js.opts.typemaps ? initCustomPointerTypemaps(xml2js.opts.typemaps) : Promise.resolve(),
fs.readFileAsync(NAMESPACE_SPEC, 'utf8'),
fs.readFileAsync(NAMESPACE_SPEC, 'utf8'),
fs.existsSync(TYPES_SPEC) ? fs.readFileAsync(TYPES_SPEC, 'utf8') : Promise.resolve(null),
function(xmlparser, ignore, xml, xml_types) {
if (xml_types != null) {
@ -202,7 +202,7 @@ var xml2js = {
validateMethods();
validateVars();
generateCustomPointerClasses();
return _.pick(xml2js, 'MODULE', 'ENUMS', 'ENUMS_BY_GROUP', 'METHODS', 'CLASSES', 'CLASSGROUPS');
return _.pick(xml2js, 'MODULE', 'ENUMS', 'ENUMS_BY_GROUP', 'METHODS', 'CLASSES', 'CLASSGROUPS');
});
}
};
@ -216,7 +216,7 @@ function createXmlParser(XML_GRAMMAR_SPEC) {
}
// configure c->js typemaps from custom swig directives
// configure c->js typemaps from custom swig directives
// TODO: many built in assumptions based on current upm file structures & .i customizations
function initCustomPointerTypemaps(typemapsdir) {
return fs.readdirAsync(typemapsdir).then(function(dirs) {
@ -391,7 +391,7 @@ function generateCustomPointerClasses() {
}
// override autogenerated methods with custom configuration
// override autogenerated methods with custom configuration
function customizeMethods(custom) {
_.each(custom, function(classMethods, className) {
_.extend(xml2js.CLASSES[className].methods, _.pick(classMethods, function(methodSpec, methodName) {
@ -401,7 +401,7 @@ function customizeMethods(custom) {
}
// make sure methods have valid types, otherwise warn (& don't include if strict)
// make sure methods have valid types, otherwise warn (& don't include if strict)
function validateMethods() {
xml2js.METHODS = _.pick(xml2js.METHODS, function(methodSpec, methodName) {
return hasValidTypes(methodSpec, methodName);
@ -428,18 +428,18 @@ function validateVars() {
}
});
}
// verify that the json spec is well formatted
function isValidMethodSpec(methodSpec, methodName) {
var valid = true;
var printIgnoredMethodOnce = _.once(function() { console.log(methodName + ' from ' + path.basename(xml2js.opts.custom) + ' is omitted from JS documentation.'); });
function checkRule(rule, errMsg) {
function checkRule(rule, errMsg) {
if (!rule) {
printIgnoredMethodOnce();
console.log(' ' + errMsg);
valid = false;
}
}
}
checkRule(_.has(methodSpec, 'description'), 'no description given');
checkRule(_.has(methodSpec, 'params'), 'no params given (specify "params": {} for no params)');
@ -452,17 +452,17 @@ function isValidMethodSpec(methodSpec, methodName) {
checkRule(_.has(methodSpec.return, 'description'), 'no description given for return value');
return valid;
}
// get enum specifications
function getEnums(spec_c, bygroup, parent) {
var spec_js = {};
var enumGroups = _.find(getChildren(spec_c, 'sectiondef'), function(section) {
var enumGroups = _.find(getChildren(spec_c, 'sectiondef'), function(section) {
var kind = getAttr(section, 'kind');
return ((kind == 'enum') || (kind == 'public-type'));
return ((kind == 'enum') || (kind == 'public-type'));
});
if (enumGroups) {
_.each(enumGroups.children, function(enumGroup) {
_.each(enumGroups.children, function(enumGroup) {
var enumGroupName = getText(getChild(enumGroup, 'name'), 'name');
var enumGroupDescription = getText(getChild(enumGroup, 'detaileddescription'), 'description');
var enumGroupVals = getChildren(enumGroup, 'enumvalue');
@ -503,7 +503,7 @@ function getDescription(spec_c) {
}
// get the classes (xml file names) for the given module
// get the classes (xml file names) for the given module
function getSubclasses(spec_c) {
return _.map(getChildren(spec_c, 'innerclass'), function(innerclass) {
return getAttr(innerclass, 'refid');
@ -511,7 +511,7 @@ function getSubclasses(spec_c) {
}
// get the classes (class names) for the given module
// get the classes (class names) for the given module
function getSubclassNames(spec_c) {
return _.map(getChildren(spec_c, 'innerclass'), function(innerclass) {
return getText(innerclass).replace(xml2js.opts.module + '::', '');
@ -528,7 +528,7 @@ function getSubmodules(spec_c) {
function hasParams(paramsSpec) {
return !(_.isEmpty(paramsSpec) ||
return !(_.isEmpty(paramsSpec) ||
((_.size(paramsSpec) == 1) && getText(getChild(paramsSpec[0], 'type')) == 'void'));
}
@ -545,7 +545,7 @@ function getMethods(spec_c, parent) {
if (methods) {
_.each(methods.children, function(method) {
var methodName = getText(getChild(method, 'name'), 'name');
if (methodName[0] != '~') { // filter out destructors
if (methodName[0] != '~') { // filter out destructors
try {
var description = getChild(method, 'detaileddescription');
var methodDescription = getText(description, 'description');
@ -616,7 +616,7 @@ function getParams(spec_c, details, method, parent) {
_.each(spec_c, function(param) {
try {
var paramType = getType(getText(getChild(param, 'type'), 'type'), parent);
var paramName = getText(getChild(param, 'declname'), 'name');
var paramName = getText(getChild(param, 'declname'), 'name');
spec_js[paramName] = { type: paramType };
} catch(e) {
if (paramType == '...') {
@ -672,7 +672,7 @@ function getType(type_c, parent) {
// verify that all types associated with the method are valid
function hasValidTypes(methodSpec, methodName, parent) {
var valid = true;
var valid = true;
var msg = (xml2js.opts.strict ? ' is omitted from JS documentation.' : ' has invalid type(s).');
var printIgnoredMethodOnce = _.once(function() { console.log(methodName + msg); });
_.each(methodSpec.params, function(paramSpec, paramName) {
@ -768,7 +768,7 @@ function getReturnDetails(spec_c) {
// get (and flatten) the text of the given object
function getText(obj, why) {
// TODO: links ignored for now, patched for types for
// TODO: links ignored for now, patched for types for
var GENERATE_LINK = function(x) { return x + ' '; }
return _.reduce(obj.children, function(text, elem) {
if (_.isString(elem)) {
@ -804,7 +804,9 @@ function getText(obj, why) {
return text += '&ndash; ';
default:
// TODO: incomplete list of doxygen xsd implemented
throw new Error('NYI Unknown Object Type: ' + elem.name);
console.warn('NYI Unknown Object Type: ' + elem.name);
return text;
//throw new Error('NYI Unknown Object Type: ' + elem.name);
}
} else {
throw new Error('NYI Unknown Type: ' + (typeof elem));
@ -842,5 +844,5 @@ function printObj(obj) {
console.log(util.inspect(obj, false, null));
}
module.exports = xml2js;