apidoc - npm Package Compare versions

Comparing version 0.12.3 to 0.13.0

CHANGELOG.md

 # apiDoc Changelog
 
+
+#### 0.13.0
+
+**Important changes**:
+  * __Remove__ deprecated annotations [http://apidocjs.com/deprecated.html].
+  * __Replace__ markdown parser (markdown-it)[https://github.com/markdown-it/markdown-it].
+
+* CLI
+  * Add path to config file (with `-c`).
+  * Add multiple input locations (with `-i`).
+  * Remove markdown config parameters, for custom configurations view [MARKDOWN.md].
+  * Disable warning if packageJson.apidoc was defined.
+  * Add litcoffee and scala file extension.
+
+* Template
+  * Add `template.forceLanguage` in `apidoc.json` to set a fixed language file without auto-detect the browser language.
+  * Add word wrap for pure text examples.
+  * Add Brazilian, French, Polish and Russian translation files.
+
+* Parser
+  * Remove deprecated annotations [http://apidocjs.com/deprecated.html].
+  * Replace markdown parser with (markdown-it)[https://github.com/markdown-it/markdown-it].
+  * Add custom markdown parser support, view [MARKDOWN.md] for details.
+  * Add support for markdown in the type section. Example: `@apiParam {(CustomType)[http://...link-to-description.html]}`
+
+
 #### 0.12.2
@@ -4,0 +30,0 @@

CONTRIBUTORS.md

@@ -5,2 +5,32 @@ # apiDoc Contributors
 
+* [Frank Lucht](https://github.com/Digigoodz)
+  * Add multiple input locations [#239](https://github.com/apidoc/apidoc/pull/239)
+
+* [赵健](https://github.com/karboom)
+  * Add word wrap for text examples [#241](https://github.com/apidoc/apidoc/pull/241)
+
+* [Tyler Clemens](https://github.com/tielur)
+  * Add a check to see if packageJson.apidoc was defined [#227](https://github.com/apidoc/apidoc/pull/227)
+
+* [Dmitry Krasyukov](https://github.com/p00h), [Alexej Yaroshevich](https://github.com/zxqfox), [Dmitry Kirilyuk](https://github.com/Jokero)
+  * Add Russian translation [#237](https://github.com/apidoc/apidoc/pull/237)
+
+* [Bruno Wego](https://github.com/brunowego)
+  * Add Brazilian translation [#249](https://github.com/apidoc/apidoc/pull/249)
+
+* [Rafał Zielonka](https://github.com/Bombaharris)
+  * Add Polish translation [#199](https://github.com/apidoc/apidoc/pull/199)
+
+* [Vincent Hérilier](https://github.com/vherilier)
+  * Add French translation [#191](https://github.com/apidoc/apidoc/pull/191)
+
+* [Hector Hernandez](https://github.com/alfadormx)
+  * Added support for markdown in the type section [#1](https://github.com/apidoc/apidoc-core/pull/1)
+
+* [Goonoo Kim](https://github.com/mctenshi)
+  * Added litcoffee file extension [#5](https://github.com/apidoc/apidoc-core/pull/5)
+
+* [Nil Gradisnik](https://github.com/nilgradisnik)
+  * Added scala file extension [#2](https://github.com/apidoc/apidoc-core/pull/2)
+
 * [Christopher Martin](https://github.com/chris-martin)
@@ -10,9 +40,9 @@ * Unindent strings [#173](https://github.com/apidoc/apidoc/pull/173)
 * [大鼻子](https://github.com/wohugb)
-  * Add chinese translation (missing translations from google).
+  * Add chinese translation (missing translations from google)
 
 * [kimhoo](https://github.com/kimhoo)
-  * Add dutch translation (missing translations from google).
+  * Add dutch translation (missing translations from google)
 
 * [Danny Olson](https://github.com/dbolson)
-  * Add Clojure parser.
+  * Add Clojure parser
 
@@ -19,0 +49,0 @@ * [Eugene Jo](https://github.com/iameugenejo)

example/_apidoc.js

@@ -14,8 +14,8 @@ // ------------------------------------------------------------------------------------------
 /**
- * @apiDefineErrorStructure CreateUserError
+ * @apiDefine CreateUserError
  * @apiVersion 0.2.0
- * 
+ *
  * @apiError NoAccessRight Only authenticated Admins can access the data.
  * @apiError UserNameTooShort Minimum of 5 characters required.
- * 
+ *
  * @apiErrorExample  Response (example):
@@ -33,3 +33,3 @@ *     HTTP/1.1 400 Bad Request
 /**
- * @apiDefinePermission admin Admin access rights needed. 
+ * @apiDefine admin Admin access rights needed.
  * Optionally you can write here further Informations about the permission.
@@ -47,3 +47,3 @@ *
 /**
- * @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0
+ * @apiDefine admin This title is visible in version 0.1.0 and 0.2.0
  * @apiVersion 0.1.0
@@ -97,3 +97,3 @@ */
  * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
- * 
+ *
  * @apiParam {String} name Name of the User.
@@ -103,3 +103,3 @@ *
  *
- * @apiErrorStructure CreateUserError
- */
+ * @apiUse CreateUserError
+ */

example/apidoc.json

@@ -20,2 +20,2 @@ {
   }
-}
+}

example/example.js

@@ -9,3 +9,3 @@ /**
  * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
- * 
+ *
  * @apiParam {Number} id The Users-ID.
@@ -17,3 +17,3 @@ *
  * @apiSuccess {Number}   id            The Users-ID.
- * @apiSuccess {Date}     registered    Registration Date. 
+ * @apiSuccess {Date}     registered    Registration Date.
  * @apiSuccess {Date}     name          Fullname of the User.
@@ -30,3 +30,3 @@ * @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).
  * @apiError UserNotFound   The <code>id</code> of the User was not found.
- * 
+ *
  * @apiErrorExample Response (example):
@@ -49,3 +49,3 @@ *     HTTP/1.1 401 Not Authenticated
  * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
- * 
+ *
  * @apiParam {String} name Name of the User.
@@ -55,3 +55,3 @@ *
  *
- * @apiErrorStructure CreateUserError
+ * @apiUse CreateUserError
  */
@@ -71,4 +71,4 @@ function postUser() { return; }
  *
- * @apiErrorStructure CreateUserError
+ * @apiUse CreateUserError
  */
-function putUser() { return; }
+function putUser() { return; }

lib/index.js

 var _        = require('lodash');
 var apidoc   = require('apidoc-core');
 var fs       = require('fs-extra');
-var markdown = require('marked');
 var path     = require('path');
 var winston  = require('winston');
+var Markdown = require('markdown-it');
 
@@ -18,15 +18,5 @@ var PackageInfo = require('./package_info');
     simulate: false,
-    parse   : false, // only parse and return the data, no file creation
+    parse   : false, // Only parse and return the data, no file creation.
     colorize: true,
-    markdown: true,
-
-    marked: {
-        gfm        : true,
-        tables     : true,
-        breaks     : false,
-        pedantic   : false,
-        sanitize   : false,
-        smartLists : false,
-        smartypants: false
-    }
+    markdown: true
 };
@@ -36,7 +26,7 @@
     log     : {},
-    markdown: false,
+    markdownParser: null,
     options : {}
 };
 
-// uncaughtException
+// Display uncaught Exception.
 process.on('uncaughtException', function(err) {
@@ -57,2 +47,3 @@ console.error((new Date()).toUTCString() + ' uncaughtException:', err.message);
     var apidocPath = path.join(__dirname, '../');
+    var markdownParser;
     var packageInfo;
@@ -62,10 +53,20 @@
 
-    // paths
+    // Paths.
     options.dest     = path.join(options.dest, './');
     options.template = path.join(options.template, './');
 
-    // options
+    // Line-Ending.
+    if (options.lineEnding) {
+        if (options.lineEnding === 'CRLF')
+            options.lineEnding = '\r\n'; // win32
+        else if (options.lineEnding === 'CR')
+            options.lineEnding = '\r'; // darwin
+        else
+            options.lineEnding = '\n'; // linux
+    }
+
+    // Options.
     app.options = options;
 
-    // logger
+    // Logger.
     app.log = new (winston.Logger)({
@@ -83,7 +84,16 @@ transports: [
 
-    // markdown
+    // Markdown Parser: enable / disable / use a custom parser.
     if(app.options.markdown === true) {
-        app.markdown = markdown;
-        app.markdown.setOptions(app.options.marked);
+        markdownParser = new Markdown({
+            breaks     : false,
+            html       : true,
+            linkify    : false,
+            typographer: false
+        });
+    } else if(app.options.markdown !== false) {
+        // Include custom Parser @see MARKDOWN.md and test/fixtures/custom_markdown_parser.js
+        Markdown = require(app.options.markdown); // Overwrite default Markdown.
+        markdownParser = new Markdown();
     }
+    app.markdownParser = markdownParser;
 
@@ -102,3 +112,3 @@ try {
         apidoc.setLogger(app.log);
-        apidoc.setMarkdownParser(app.markdown);
+        apidoc.setMarkdownParser(markdownParser);
         apidoc.setPackageInfos(packageInfo.get());
@@ -105,0 +115,0 @@

lib/package_info.js

@@ -47,4 +47,4 @@ var _    = require('lodash');
 
-    if (Object.keys(apidocJson).length === 0)
-        app.log.warn('Please create an apidoc.json.');
+    if (Object.keys(apidocJson).length === 0 && ! packageJson.apidoc)
+        app.log.warn('Please create an apidoc.json configuration file.');
 
@@ -64,11 +64,12 @@ return result;
     var result = {};
-    var jsonFilename = path.join(app.options.src, filename);
+    var dir = this._resolveSrcPath();
+    var jsonFilename = path.join(dir, filename);
 
-    // read from source dir
+    // Read from source dir
     if ( ! fs.existsSync(jsonFilename)) {
-        // read vom current dir
-        jsonFilename = './' + filename;
+        // Read from config dir (default './')
+        jsonFilename = path.join(app.options.config, filename);
     }
     if ( ! fs.existsSync(jsonFilename)) {
-        app.log.debug(filename + ' not found!');
+        app.log.debug(jsonFilename + ' not found!');
     } else {
@@ -93,6 +94,10 @@ try {
     var result = {};
+    var self = this;
 
     ['header', 'footer'].forEach(function(key) {
         if (json[key] && json[key].filename) {
-            var filename = path.join(app.options.src, json[key].filename);
+//            var filename = path.join(app.options.src, json[key].filename);
+            var dir = self._resolveSrcPath();
+            var filename = path.join(dir, json[key].filename);
+
             if ( ! fs.existsSync(filename))
@@ -106,3 +111,3 @@ filename = path.join('./', json[key].filename);
                     title  : json[key].title,
-                    content: app.markdown ? app.markdown(content) : content
+                    content: app.markdownParser ? app.markdownParser.render(content) : content
                 };
@@ -117,1 +122,20 @@ } catch (e) {
 };
+
+/**
+ * Resolve source path.
+ *
+ * If multiple input dirs are given, the current workdir './' will be returned.
+ * On one input dir, the current workdir will be the input dir.
+ *
+ * @returns {string}
+ * @private
+ */
+PackageInfo.prototype._resolveSrcPath = function() {
+    var dir = './';
+
+    if (app.options.src instanceof Array && app.options.src.length === 1)
+        dir = app.options.src[0];
+
+    return dir;
+};
+

package.json

 {
   "name": "apidoc",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "RESTful web API Documentation Generator",
@@ -39,6 +39,6 @@ "author": "Peter Rottmann <[e-mail]>",
   "dependencies": {
-    "apidoc-core": "~0.3.2",
-    "fs-extra": "~0.18.1",
-    "lodash": "~3.6.0",
-    "marked": "~0.3.3",
+    "apidoc-core": "~0.4.0",
+    "fs-extra": "~0.18.2",
+    "lodash": "~3.8.0",
+    "markdown-it": "^4.2.1",
     "nomnom": "~1.8.1",
@@ -53,3 +53,3 @@ "winston": "~1.0.0"
     "path-to-regexp": "^1.0.3",
-    "semver": "^4.3.3",
+    "semver": "^4.3.4",
     "should": "~6.0.1"
@@ -56,0 +56,0 @@ },

README.md

@@ -53,3 +53,3 @@ # apiDoc
 
- * **C#, Go, Dart, Java, JavaScript, PHP** (all DocStyle capable languages):
+ * **C#, Go, Dart, Java, JavaScript, PHP, Scala** (all DocStyle capable languages):
 
@@ -133,2 +133,8 @@ ```javascript
 
+## Converter
+
+* [apidoc-swagger](https://github.com/fsbahman/apidoc-swagger)
+* [gulp-apidoc-swagger](https://github.com/fsbahman/gulp-apidoc-swagger)
+
+
 ## Help
@@ -135,0 +141,0 @@

template/locales/locale.js

 define([
     './locales/de.js',
+    './locales/fr.js',
     './locales/nl.js',
+    './locales/pl.js',
+    './locales/pt_br.js',
+    './locales/ru.js',
     './locales/zh.js'
 ], function() {
+    var langId = (navigator.language || navigator.userLanguage).toLowerCase();
+    var language = langId.substr(0, 2);
     var locales = {};
-    for(index in arguments) {
-        for(property in arguments[index]) {
+
+    for (index in arguments) {
+        for (property in arguments[index])
             locales[property] = arguments[index][property];
-        }
     }
+    if ( ! locales['en'])
+        locales['en'] = {};
 
-    var language = ((navigator.language) ? navigator.language : navigator.userLanguage).substr(0, 2).toLowerCase();
-    if( ! locales['en'])
-        locales['en'] = {};
-    if( ! locales[language])
+    if ( ! locales[langId] && ! locales[language])
         language = 'en';
 
-    var locale = locales[language];
+    var locale = (locales[langId] ? locales[langId] : locales[language]);
 
-    var __ = function(text) {
+    function __(text) {
         var index = locale[text];
-        if(index === undefined) return text;
+        if (index === undefined)
+            return text;
         return index;
     };
 
+    function setLanguage(language) {
+        locale = locales[language];
+    }
+
     return {
-        __     : __,
-        locales: locales,
-        locale : locale
+        __         : __,
+        locales    : locales,
+        locale     : locale,
+        setLanguage: setLanguage
     };
 });

template/main.js

@@ -78,2 +78,5 @@ require.config({
 
+    if (apiProject.template.forceLanguage)
+        locale.setLanguage(apiProject.template.forceLanguage);
+
     // Setup jQuery Ajax
@@ -80,0 +83,0 @@ $.ajaxSetup(apiProject.template.jQueryAjaxSetup);

New alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

622216

1.56%

Number of package files

75

8.7%

Lines of code

4218

3.56%

Number of lines in readme file

146

4.29%

Worsened metrics

Number of low supply chain risk alerts

8

14.29%

Dependency changes

• + Added

  markdown-it@^4.2.1

• + Added

  apidoc-core@0.4.2
  (transitive)

• + Added

  argparse@1.0.10
  (transitive)

• + Added

  entities@1.1.2
  (transitive)

• + Added

  linkify-it@1.2.4
  (transitive)

• + Added

  lodash@3.10.13.8.0
  (transitive)

• + Added

  markdown-it@4.4.0
  (transitive)

• + Added

  mdurl@1.0.1
  (transitive)

• + Added

  semver@5.1.1
  (transitive)

• + Added

  sprintf-js@1.0.3
  (transitive)

• + Added

  uc.micro@1.0.6
  (transitive)

• - Removed

  marked@~0.3.3

• - Removed

  apidoc-core@0.3.2
  (transitive)

• - Removed

  lodash@3.6.0
  (transitive)

• - Removed

  marked@0.3.19
  (transitive)

• - Removed

  semver@4.3.6
  (transitive)

• Updated

  apidoc-core@~0.4.0

• Updated

  fs-extra@~0.18.2

• Updated

  lodash@~3.8.0