diff --git a/doxy/node/xml2js.js b/doxy/node/xml2js.js index 7f85a30e..48431c8b 100644 --- a/doxy/node/xml2js.js +++ b/doxy/node/xml2js.js @@ -36,7 +36,7 @@ Promise.promisifyAll(fs); var xml2js = { - + // js-format specs // MODULE: // ENUMS: { @@ -47,7 +47,7 @@ var xml2js = { // } // ENUMS_BY_GROUP: { // : { - // description: + // description: // members: [ , ... ] // }, ... // } @@ -58,7 +58,7 @@ var xml2js = { // : { // type: , // description: - // }, ... + // }, ... // }, // return: { // type: , @@ -79,7 +79,7 @@ var xml2js = { // enums: { ... }, // enums_by_group: { ... } // }, ... - // } + // } // CLASSGROUPS: { // : { // 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: { // : { // arrayType: , // classes: [ , ... ] // }, ... - // } + // } // POINTER_TYPEMAPS: { // : { // : , ... @@ -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 += '– '; 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; \ No newline at end of file