apidoc-core - npm Package Compare versions

Comparing version 0.12.0 to 0.15.0

CHANGELOG.md

 # Changelog for apidoc-core
 
+## 0.15.0
+
+### Fixed
+* Fix incorrect return type in @apiPrivate parser (PR #112 from nomoon)
+
+## 0.14.0
+
+### Added
+
+* Implement apiBody and apiQuery tags by @SWheeler17 #104
+* Expose parseSource function by @woodgear #109
+* Add GitHub actions by @tommy87 #107
+
+## 0.13.0
+
+### Added
+
+* Enable the use of an apiUse block in an apiDefine block (#99 by tommy87)
+
 ## 0.12.0
@@ -4,0 +23,0 @@

lib/index.js

@@ -64,2 +64,4 @@ var _      = require('lodash');
         api                      : './parsers/api.js',
+        apibody                  : './parsers/api_body.js',
+        apiquery                 : './parsers/api_query.js',
         apidefine                : './parsers/api_define.js',
@@ -152,43 +154,7 @@ apidescription           : './parsers/api_description.js',
 function parse(options) {
-    options = _.defaults({}, options, defaults);
-
-    // extend with custom functions
-    app.filters   = _.defaults({}, options.filters, app.filters);
-    app.languages = _.defaults({}, options.languages, app.languages);
-    app.parsers   = _.defaults({}, options.parsers, app.parsers);
-    app.workers   = _.defaults({}, options.workers, app.workers);
-    app.hooks     = _.defaults({}, options.hooks, app.hooks);
-
-    // options
-    app.options = options;
-
-    // generator
-    app.generator = _.defaults({}, app.generator, defaultGenerator);
-
-    // packageInfos
-    app.packageInfos = _.defaults({}, app.packageInfos, defaultPackageInfos);
-
-    var parsedFiles = [];
-    var parsedFilenames = [];
-
     try {
-        // Log version information
-        var filename = path.join(__dirname, '../', './package.json');
-        var packageJson = JSON.parse( fs.readFileSync( filename , 'utf8') );
-        app.log.verbose('apidoc-generator name: '    + app.generator.name);
-        app.log.verbose('apidoc-generator version: ' + app.generator.version);
-        app.log.verbose('apidoc-core version: '      + packageJson.version);
-        app.log.verbose('apidoc-spec version: '      + getSpecificationVersion());
-
-        new PluginLoader(app);
-
-        var parser = new Parser(app);
-        var worker = new Worker(app);
-        var filter = new Filter(app);
-
-        // Make them available for plugins
-        app.parser = parser;
-        app.worker = worker;
-        app.filter = filter;
-
+        initApp(options);
+        options = app.options;
+        var parsedFiles = [];
+        var parsedFilenames = [];
         // if input option for source is an array of folders,
@@ -203,3 +169,3 @@ // parse each folder in the order provided.
                 folderOptions.src = path.join(folder, './');
-                parser.parseFiles(folderOptions, parsedFiles, parsedFilenames);
+                app.parser.parseFiles(folderOptions, parsedFiles, parsedFilenames);
             });
@@ -210,3 +176,3 @@ }
             options.src = path.join(options.src, './');
-            parser.parseFiles(options, parsedFiles, parsedFilenames);
+            app.parser.parseFiles(options, parsedFiles, parsedFilenames);
         }
@@ -217,7 +183,7 @@
             app.log.verbose('run worker');
-            worker.process(parsedFiles, parsedFilenames, app.packageInfos);
+            app.worker.process(parsedFiles, parsedFilenames, app.packageInfos);
 
             // cleanup
             app.log.verbose('run filter');
-            var blocks = filter.process(parsedFiles, parsedFilenames);
+            var blocks = app.filter.process(parsedFiles, parsedFilenames);
 
@@ -308,2 +274,61 @@ // sort by group ASC, name ASC, version DESC
 /**
+ * parseSource
+ *
+ * @param {string} source        the source code string.
+ * @param {Object} options        Overwrite default options.
+ */
+function parseSource(source, options) {
+    try {
+        initApp(options);
+        return app.parser.parseSource(source, app.options.encoding, app.options.filename);
+    } catch (e) {
+        app.log.error(e.message);
+    }
+}
+
+/**
+ * initApp
+ *
+ * @param {Object} options        Overwrite default options.
+ */
+function initApp(options) {
+
+    options = _.defaults({}, options, defaults);
+    // extend with custom functions
+    app.filters   = _.defaults({}, options.filters, app.filters);
+    app.languages = _.defaults({}, options.languages, app.languages);
+    app.parsers   = _.defaults({}, options.parsers, app.parsers);
+    app.workers   = _.defaults({}, options.workers, app.workers);
+    app.hooks     = _.defaults({}, options.hooks, app.hooks);
+
+    // options
+    app.options = options;
+
+    // generator
+    app.generator = _.defaults({}, app.generator, defaultGenerator);
+
+    // packageInfos
+    app.packageInfos = _.defaults({}, app.packageInfos, defaultPackageInfos);
+
+    // Log version information
+    var filename = path.join(__dirname, '../', './package.json');
+    var packageJson = JSON.parse( fs.readFileSync( filename , 'utf8') );
+    app.log.verbose('apidoc-generator name: '    + app.generator.name);
+    app.log.verbose('apidoc-generator version: ' + app.generator.version);
+    app.log.verbose('apidoc-core version: '      + packageJson.version);
+    app.log.verbose('apidoc-spec version: '      + getSpecificationVersion());
+
+    new PluginLoader(app);
+
+    var parser = new Parser(app);
+    var worker = new Worker(app);
+    var filter = new Filter(app);
+
+    // Make them available for plugins
+    app.parser = parser;
+    app.worker = worker;
+    app.filter = filter;
+} 
+
+/**
  * Set generator informations.
@@ -410,2 +435,3 @@ *
     parse                  : parse,
+    parseSource            : parseSource,
     setGeneratorInfos      : setGeneratorInfos,
@@ -412,0 +438,0 @@ setLogger              : setLogger,

lib/parser.js

@@ -128,2 +128,10 @@ var _    = require('lodash');
     var fileContent = fs.readFileSync(filename, { encoding: 'binary' });
+    return self.parseSource(fileContent,encoding,filename);
+};
+
+/**
+ * Execute Sourceparsing
+ */
+Parser.prototype.parseSource = function(fileContent,encoding,filename) {
+    var self = this;
     iconv.skipDecodeWarning = true;
@@ -226,3 +234,3 @@ self.src = iconv.decode(fileContent, encoding);
                     // allow multiple inserts into pathTo
-                    allowMultiple = elementParser.allowMultiple === true;
+                    allowMultiple = true;
 
@@ -229,0 +237,0 @@

lib/parsers/api_private.js

 function parse() {
-    return 'private';
+    return {
+        private: true
+    };
 }
@@ -4,0 +6,0 @@

lib/workers/api_use.js

@@ -69,11 +69,6 @@ var _ = require('lodash');
         parsedFile.forEach(function(block) {
-            if ( ! block.local[target])
-                return;
-
-            block.local[target].forEach(function(definition) {
-                var name = definition.name;
-                var version = block.version || packageInfos.defaultVersion;
-
-                if ( ! preProcess[source] || ! preProcess[source][name]) {
-                    throw new WorkerError('Referenced groupname does not exist / it is not defined with @apiDefine.',
+            var loopCounter = 0;     //add a loop counter to have a break condition when the recursion depth exceed a predifined limit
+            while (block.local[target]) {
+                if (loopCounter > 10) {
+                    throw new WorkerError('recursion depth exceeds limit with @apiUse',
                         filenames[parsedFileIndex],
@@ -85,3 +80,3 @@ block.index,
                         [
-                            { 'Groupname': name }
+                           { 'Groupname': block.name }
                         ]
@@ -91,22 +86,16 @@ );
 
-                var matchedData = {};
-                if (preProcess[source][name][version]) {
-                    // found the version
-                    matchedData = preProcess[source][name][version];
-                } else {
-                    // find nearest matching version
-                    var foundIndex = -1;
-                    var lastVersion = packageInfos.defaultVersion;
+                //create a copy of the elements for save iterating of the elements
+                var blockClone = block.local[target].slice();
 
-                    var versionKeys = Object.keys(preProcess[source][name]);
-                    versionKeys.forEach(function(currentVersion, versionIndex) {
-                        if (semver.gte(version, currentVersion) && semver.gte(currentVersion, lastVersion)) {
-                            lastVersion = currentVersion;
-                            foundIndex = versionIndex;
-                        }
-                    });
+                // remove unneeded target before starting the loop, to allow a save insertion of new elements
+                // TODO: create a cleanup filter
+                delete block.local[target];
 
-                    if (foundIndex === -1) {
-                        throw new WorkerError('Referenced definition has no matching or a higher version. ' +
-                            'Check version number in referenced define block.',
+                for (var blockIndex = 0; blockIndex < blockClone.length; ++blockIndex) {
+                    var definition = blockClone[blockIndex];
+                    var name = definition.name;
+                    var version = block.version || packageInfos.defaultVersion;
+
+                    if ( ! preProcess[source] || ! preProcess[source][name]) {
+                        throw new WorkerError('Referenced groupname does not exist / it is not defined with @apiDefine.',
                             filenames[parsedFileIndex],
@@ -118,5 +107,3 @@ block.index,
                             [
-                                { 'Groupname': name },
-                                { 'Version': version },
-                                { 'Defined versions': versionKeys },
+                                { 'Groupname': name }
                             ]
@@ -126,13 +113,44 @@ );
 
-                    var versionName = versionKeys[foundIndex];
-                    matchedData = preProcess[source][name][versionName];
-                }
+                    var matchedData = {};
+                    if (preProcess[source][name][version]) {
+                        // found the version
+                        matchedData = preProcess[source][name][version];
+                    } else {
+                        // find nearest matching version
+                        var foundIndex = -1;
+                        var lastVersion = packageInfos.defaultVersion;
 
-                // remove target, not needed anymore
-                // TODO: create a cleanup filter
-                delete block.local[target];
+                        var versionKeys = Object.keys(preProcess[source][name]);
+                        for (var versionIndex = 0; versionIndex < versionKeys.length; ++versionIndex) {
+                            var currentVersion = versionKeys[versionIndex];
+                            if (semver.gte(version, currentVersion) && semver.gte(currentVersion, lastVersion)) {
+                                lastVersion = currentVersion;
+                                foundIndex = versionIndex;
+                            }
+                        }
 
-                // copy matched elements into parsed block
-                _recursiveMerge(block.local, matchedData);
-            });
+                        if (foundIndex === -1) {
+                            throw new WorkerError('Referenced definition has no matching or a higher version. ' +
+                                'Check version number in referenced define block.',
+                                filenames[parsedFileIndex],
+                                block.index,
+                                messages.common.element,
+                                messages.common.usage,
+                                messages.common.example,
+                                [
+                                    { 'Groupname': name },
+                                    { 'Version': version },
+                                    { 'Defined versions': versionKeys },
+                                ]
+                            );
+                        }
+
+                        var versionName = versionKeys[foundIndex];
+                        matchedData = preProcess[source][name][versionName];
+                    }
+
+                    // copy matched elements into parsed block
+                    _recursiveMerge(block.local, matchedData);
+                }
+            }
         });
@@ -139,0 +157,0 @@ });

package.json

 {
   "name": "apidoc-core",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "Core parser library to generate apidoc result following the apidoc-spec",
@@ -5,0 +5,0 @@ "author": "Peter Rottmann <[e-mail]>",

README.md

@@ -5,3 +5,3 @@ # apidoc-core
 
-[![Build Status](https://travis-ci.org/apidoc/apidoc-core.svg?branch=master)](https://travis-ci.org/apidoc/apidoc-core)
+![Build Status](https://github.com/apidoc/apidoc-core/workflows/validate/badge.svg)
 [![Dependency Status](https://david-dm.org/apidoc/apidoc-core.svg)](https://david-dm.org/apidoc/apidoc-core)
@@ -8,0 +8,0 @@ [![NPM version](https://badge.fury.io/js/apidoc-core.svg)](http://badge.fury.io/js/apidoc-core)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

118474

increased by4.9%

Number of package files

70

increased by7.69%

Lines of code

3044

increased by5.4%

No dependency changes