diff --git a/.eslintrc.json b/.eslintrc.json index 3ecd48f8..d99a9226 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -43,7 +43,59 @@ "named": "always", "asyncArrow": "ignore" }], - "space-infix-ops": ["error", { "int32Hint": true }] + "space-infix-ops": ["error", { "int32Hint": true }], + "jsdoc/check-access": 1, + "jsdoc/check-alignment": 1, + "jsdoc/check-line-alignment": 1, + "jsdoc/check-param-names": 1, + "jsdoc/check-property-names": 1, + "jsdoc/check-tag-names": 1, + "jsdoc/check-types": 1, + "jsdoc/check-values": 1, + "jsdoc/empty-tags": 1, + "jsdoc/multiline-blocks": 1, + "jsdoc/newline-after-description": 1, + "jsdoc/no-multi-asterisks": 1, + "jsdoc/require-param": 1, + "jsdoc/require-param-name": 1, + "jsdoc/require-param-type": 1, + "jsdoc/require-property": 1, + "jsdoc/require-property-name": 1, + "jsdoc/require-property-type": 1, + "jsdoc/require-returns-type": 1, + "jsdoc/require-yields": 1, + "jsdoc/require-yields-check": 1, + "jsdoc/tag-lines": 1, + "jsdoc/valid-types": 1, + "jsdoc/sort-tags": [ + "warn", + { + "tagSequence": [ + "global", + "typedef", + "var", + "name", + "namespace", + "constructor", + "callback", + "event", + "function", + "augments", + "lends", + "type", + "prop", + "param", + "throws", + "fires", + "listens", + "ingroup", + "deprecated", + "see", + "todo", + "ignore" + ] + } + ] }, "globals": { "PR": true, @@ -54,5 +106,7 @@ "after": true, "afterEach": true }, - "plugins": [] + "plugins": [ + "jsdoc" + ] } diff --git a/docs/adm-nodes.jpeg b/docs/adm-nodes.jpeg deleted file mode 100644 index c8f3f8e7..00000000 Binary files a/docs/adm-nodes.jpeg and /dev/null differ diff --git a/docs/conf.json b/docs/conf.json deleted file mode 100644 index d33879a0..00000000 --- a/docs/conf.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "tags": { - "allowUnknownTags": true, - "dictionaries": ["jsdoc"] - }, - "source": { - "include": [ - "./docs/typedef/", - "./app.js", - "./api/http/", - "./helpers/", - "./logic/", - "./modules/", - "./schema/" - ], - "exclude": [ "./public", "./node_modules"] - }, - "plugins": ["plugins/markdown"], - "opts": { - "readme": "docs/intro.md", - "encoding": "utf8", - "destination": "./docs/jsdoc", - "recurse": true - }, - "templates": { - "cleverLinks": false - } -} diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index c6061c5a..00000000 --- a/docs/intro.md +++ /dev/null @@ -1,210 +0,0 @@ -![Lisk Logo](https://lisk.io/i/mediakit/logo_1.png) - -# Lisk JSDoc Source code documentation - -This is an ongoing process -## Best Practices -* To indicate the data type for a `@param` or `@return` tag, put the data type in `{}` brackets: `@param {TheType} paramName` or `@return {TheType}`. -For non-object data, use `number`, `string`, `boolean`, `null`, `undefined`, `Object`, `function`, `Array`. -For particular objects, use the constructor name; this could be a built-in JavaScript class (`Date`, `RegExp`) or custom classes. -* This can be a number or a boolean. `{(number|boolean)}` -* A number or null: `{?number}` -* A number, but never null: `{!number}` -* Variable number of that type `@param {...number} num` -* Optional parameter `@param {number} [foo]` or `@param {number=} foo` -* An optional parameter foo with default value 1. `@param {number} [foo=1]` -* [multiple types and repeatable parameters](http://usejsdoc.org/tags-param.html#multiple-types-and-repeatable-parameters) - -* when documenting an object that is not being used as a `namespace` or `class`, use `@prop {type} name` tags to document its properties (these work like `@param` for function parameters). - -* Use `@name` to tell JSDoc the name of what is being documented, if it is not the same as the name in the code. - -* No need to use `@function` in most cases - JSDoc will assume anything declared as a function is a regular function or method. - -#### Tag order -Tags available should be declared in the following order: -``` js -@global - -@typedef -@var -@name -@namespace -@constructor -@callback -@event -@function - -@augments -@lends - -@type -@prop - -@param -@return - -@throws -@fires -@listens - -@ingroup -@deprecated -@see -@todo -@ignore -``` - -## Syntax -### General -`@description `: -Can omit this tag if description is located at the beginning - -### Membership -`@namespace [[{}] ]`: -an object creates a namespace for its members. - -`@memberof `: -identifies a member symbol that belongs to a parent symbol. -`@memberof! `: - forces JSDoc to document a property of an object that is an instance member of a class. -[Examples](http://usejsdoc.org/tags-memberof.html#examples) - -### Relational -`@implements {typeExpression}`: -a symbol implements an interface. - -`@interface []`: -marks a symbol as an interface that other symbols can implement. - -`@external `: -identifies a class, namespace, or module that is defined outside of the current package. -`@see ` to add a link - -### Entities -`@class [ ]`: -marks a function as being a constructor, meant to be called with the new keyword to return an instance. - -`@function []`: -marks an object as being a function, even though it may not appear to be one to the parser - -`@module [[{}] module:]`: -marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise. - -`@static`: -symbol is contained within a parent and can be accessed without instantiating the parent. - -#### Symbols, Parameters, Variables -`@type {typeName}`: -allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. -[examples](http://usejsdoc.org/tags-type.html) - -`@typedef [] `: -custom types, particularly if you wish to refer to them repeatedly. - -`@private | @public | @protected`: -* public: JSDoc treats all symbols as public -* proceted: a symbol is only available, or should only be used, within the current module. - -`@inner vs @global`: - -### Beavior -`@param {type} name - description`: -name, type, and description of a function parameter. -[examples](http://usejsdoc.org/tags-param.html) - -`@returns`: - -`@callback`: -callback function that can be passed to other functions. - -`@throws {} free-form description`: -an error that a function might throw. - -### Events -`@event #[event:]`: - -`@listens `: - indicates that a symbol listens for the specified event. - -`@fires #[event:]`: - -`@mixin`: -This provides methods used for event handling - -## Examples - -#### document namespaces - -``` js -/** @namespace */ -hgm = {}; - -/** @namespace */ -hgm.cookie = { - /** describe me */ - get: function (name) { }, - - /** describe me */ - set: function (name, value) { }, - - /** describe me */ - remove: function (name) { } -}; -``` - -#### A namespace with defaults and nested default properties -``` js -/** - * @namespace - * @property {object} defaults - The default values for parties. - * @property {number} defaults.players - The default number of players. - * @property {string} defaults.level - The default level for the party. - * @property {object} defaults.treasure - The default treasure. - * @property {number} defaults.treasure.gold - How much gold the party starts with. - */ -var config = { - defaults: { - players: 1, - level: 'beginner', - treasure: { - gold: 0 - } - } -}; -``` - -#### Documenting large apps, group modules into categories - -> This is to represent and explore functional behavior. - -Example: Account module is composed by: -* api -* modules -* logic -* schema -* helpers - -``` js -/**Parent module -* @module package-name -*/ - -/**Child of the parent module -* @namespace firstChild -* @memberof module:package-name -*/ -``` - -#### ToDO - -- [ ] JSDoc template -- [ ] Markdown plugin -- [ ] Use categories tag: `@categories` -- [ ] Patterns examples -- [ ] More Lisk examples: callback, throws, class, nested objects -- [ ] JSDoc tutorials for best practices -- [ ] Callback patterns - * node style: cb(err, data); - `app.js` - * setImmediate style: return setImmediate(cb, null, data); - `modules/blocks.js` - * next style: cb(); - `app.js` \ No newline at end of file diff --git a/docs/typedef/components.js b/docs/typedef/components.js deleted file mode 100644 index ceffce25..00000000 --- a/docs/typedef/components.js +++ /dev/null @@ -1,19 +0,0 @@ -/** - * Handles module content - * @typedef {Object} modules - * @property {Accounts} accounts - * @property {Blocks} blocks - * @property {Crypto} crypto - * @property {DApps} dapps - * @property {Delegates} delegates - * @property {Loader} loader - * @property {Multisignatures} multisignatures - * @property {Peers} peers - * @property {Rounds} rounds - * @property {Server} server - * @property {Signatures} signatures - * @property {Sql} sql - * @property {System} system - * @property {Transactions} transactions - * @property {transport} Transport - */ diff --git a/docs/typedef/crypto.js b/docs/typedef/crypto.js deleted file mode 100644 index d97a2b00..00000000 --- a/docs/typedef/crypto.js +++ /dev/null @@ -1,20 +0,0 @@ -/** - * Public Key obtained from sodium.crypto_sign_seed_keypair(hash) - * @typedef {string} publicKey - */ -/** - * Private Key obtained from sodium.crypto_sign_seed_keypair(hash) - * @typedef {string} privateKey - */ -/** - * Address obtained from publicKey using bignum function with 'U' in the beginning. - * @typedef {string} address - */ -/** - * Crypto hash hex - * @typedef {string} hash - */ -/** - * publicKey, privateKey - * @typedef {Object} keypair - */ diff --git a/docs/typedef/modules/accounts.js b/docs/typedef/modules/accounts.js deleted file mode 100644 index cb9f06c4..00000000 --- a/docs/typedef/modules/accounts.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `accounts` - * - * @module accounts - */ diff --git a/docs/typedef/modules/blocks.js b/docs/typedef/modules/blocks.js deleted file mode 100644 index 9e76b5f0..00000000 --- a/docs/typedef/modules/blocks.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `blocks` - * - * @module blocks - */ diff --git a/docs/typedef/modules/dapps.js b/docs/typedef/modules/dapps.js deleted file mode 100644 index 6e44a3bb..00000000 --- a/docs/typedef/modules/dapps.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `dapps` - * - * @module dapps - */ diff --git a/docs/typedef/modules/delegates.js b/docs/typedef/modules/delegates.js deleted file mode 100644 index 092e0dd6..00000000 --- a/docs/typedef/modules/delegates.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `delegates` - * - * @module delegates - */ diff --git a/docs/typedef/modules/helpers.js b/docs/typedef/modules/helpers.js deleted file mode 100644 index aaf05480..00000000 --- a/docs/typedef/modules/helpers.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Core Module `helpers` - * - * @module helpers - */ diff --git a/docs/typedef/modules/loader.js b/docs/typedef/modules/loader.js deleted file mode 100644 index d8afa350..00000000 --- a/docs/typedef/modules/loader.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `loader` - * - * @module loader - */ diff --git a/docs/typedef/modules/multisignatures.js b/docs/typedef/modules/multisignatures.js deleted file mode 100644 index 2bf920ba..00000000 --- a/docs/typedef/modules/multisignatures.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `multisignatures` - * - * @module multisignatures - */ diff --git a/docs/typedef/modules/peers.js b/docs/typedef/modules/peers.js deleted file mode 100644 index aab2edf5..00000000 --- a/docs/typedef/modules/peers.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `peers` - * - * @module peers - */ diff --git a/docs/typedef/modules/rounds.js b/docs/typedef/modules/rounds.js deleted file mode 100644 index d997442d..00000000 --- a/docs/typedef/modules/rounds.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Core Module `rounds` - * - * @module rounds - */ diff --git a/docs/typedef/modules/server.js b/docs/typedef/modules/server.js deleted file mode 100644 index c84af8c3..00000000 --- a/docs/typedef/modules/server.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `server` - * - * @module server - */ diff --git a/docs/typedef/modules/signatures.js b/docs/typedef/modules/signatures.js deleted file mode 100644 index c0224eee..00000000 --- a/docs/typedef/modules/signatures.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `signatures` - * - * @module signatures - */ diff --git a/docs/typedef/modules/transactions.js b/docs/typedef/modules/transactions.js deleted file mode 100644 index 90d356f8..00000000 --- a/docs/typedef/modules/transactions.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `transactions` - * - * @module transactions - */ diff --git a/docs/typedef/modules/transport.js b/docs/typedef/modules/transport.js deleted file mode 100644 index 543d205b..00000000 --- a/docs/typedef/modules/transport.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * Functional Module `transport` - * - * @module transport - */ diff --git a/docs/typedef/namespace.js b/docs/typedef/namespace.js deleted file mode 100644 index 8f28110c..00000000 --- a/docs/typedef/namespace.js +++ /dev/null @@ -1,5 +0,0 @@ -/** - * General object to define private functions in different main functions. - * @namespace __private - * @private - */ diff --git a/package.json b/package.json index e46a2b32..6240dbde 100644 --- a/package.json +++ b/package.json @@ -81,6 +81,7 @@ "chai-bignumber": "^3.0.0", "eslint-config-google": "^0.14.0", "eslint-formatter-codeframe": "^7.32.1", + "eslint-plugin-jsdoc": "^39.3.4", "grunt": "^1.5.3", "grunt-cli": "^1.4.3", "grunt-contrib-compress": "^2.0.0", @@ -90,6 +91,7 @@ "jsdoc": "^3.6.11", "mocha": "^10.0.0", "moment": "^2.29.4", +>>>>>>> dev "nyc": "^15.1.0", "nyc-middleware": "^1.0.4", "sinon": "^14.0.0",