Skip to content

Commit

Permalink
Remove mixin duplicates and improve JSDoc (yeoman#1175)
Browse files Browse the repository at this point in the history 
* Improve jsdoc

* Remove mixin duplicate methods from jsdoc
  • Loading branch information
@mshima
mshima committed Feb 19, 2020
1 parent b9c78ab commit ccbcc26
Showing 1 changed file with 59 additions and 63 deletions.
122 changes: 59 additions & 63 deletions lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,41 +28,6 @@ const methodIsValid = function(name) {
return name.charAt(0) !== '_' && name !== 'constructor';
};

/**
* The `Generator` class provides the common API shared by all generators.
* It define options, arguments, file, prompt, log, API, etc.
*
* It mixes into its prototype all the methods found in the `actions/` mixins.
*
* Every generator should extend this base class.
*
* @constructor
* @mixes actions/help
* @mixes actions/install
* @mixes actions/spawn-command
* @mixes actions/user
* @mixes nodejs/EventEmitter
*
* @param {String|Array} args
* @param {Object} options
*
* @property {Object} env - the current Environment being run
* @property {Object} args - Provide arguments at initialization
* @property {String} resolved - the path to the current generator
* @property {String} description - Used in `--help` output
* @property {String} appname - The application name
* @property {Storage} config - `.yo-rc` config file manager
* @property {Object} fs - An instance of {@link https://github.com/SBoudrias/mem-fs-editor Mem-fs-editor}
* @property {Function} log - Output content through Interface Adapter
*
* @example
* const Generator = require('yeoman-generator');
* module.exports = class extends Generator {
* writing() {
* this.fs.write(this.destinationPath('index.js'), 'const foo = 1;');
* }
* };
*/
class Generator extends EventEmitter {
// If for some reason environment adds more queues, we should use or own for stability.
static get queues() {
Expand All @@ -78,6 +43,40 @@ class Generator extends EventEmitter {
];
}

/**
* @classdesc The `Generator` class provides the common API shared by all generators.
* It define options, arguments, file, prompt, log, API, etc.
*
* It mixes into its prototype all the methods found in the `actions/` mixins.
*
* Every generator should extend this base class.
*
* @constructor
* @mixes actions/help
* @mixes actions/install
* @mixes actions/spawn-command
* @mixes actions/user
* @mixes nodejs/EventEmitter
*
* @param {string[]} args - Provide arguments at initialization
* @param {Object} options - Provide options at initialization
*
* @property {Object} env - the current Environment being run
* @property {String} resolved - the path to the current generator
* @property {String} description - Used in `--help` output
* @property {String} appname - The application name
* @property {Storage} config - `.yo-rc` config file manager
* @property {Object} fs - An instance of {@link https://github.com/SBoudrias/mem-fs-editor Mem-fs-editor}
* @property {Function} log - Output content through Interface Adapter
*
* @example
* const Generator = require('yeoman-generator');
* module.exports = class extends Generator {
* writing() {
* this.fs.write(this.destinationPath('index.js'), 'const foo = 1;');
* }
* };
*/
constructor(args, options) {
super();

Expand Down Expand Up @@ -283,7 +282,7 @@ class Generator extends EventEmitter {
* user's answers as defaults.
*
* @param {array} questions Array of question descriptor objects. See {@link https://github.com/SBoudrias/Inquirer.js/blob/master/README.md Documentation}
* @return {Promise}
* @return {Promise} prompt promise
*/
prompt(questions) {
questions = promptSuggestion.prefillQuestions(this._globalConfig, questions);
Expand All @@ -304,16 +303,14 @@ class Generator extends EventEmitter {
* generate generator usage. By default, generators get all the cli options
* parsed by nopt as a `this.options` hash object.
*
* ### Options:
*
* - `description` Description for the option
* - `type` Either Boolean, String or Number
* - `alias` Option name alias (example `-h` and --help`)
* - `default` Default value
* - `hide` Boolean whether to hide from help
*
* @param {String} name
* @param {Object} config
* @param {String} name - Option name
* @param {Object} config - Option options
* @param {any} config.type - Either Boolean, String or Number
* @param {string} [config.description] - Description for the option
* @param {any} [config.default] - Default value
* @param {any} [config.alias] - Option name alias (example `-h` and --help`)
* @param {any} [config.hide] - Boolean whether to hide from help
* @return {this} This generator
*/
option(name, config) {
config = config || {};
Expand Down Expand Up @@ -367,16 +364,15 @@ class Generator extends EventEmitter {
* Besides, arguments are used inside your code as a property (`this.argument`),
* while options are all kept in a hash (`this.options`).
*
* ### Options:
*
* - `description` Description for the argument
* - `required` Boolean whether it is required
* - `optional` Boolean whether it is optional
* - `type` String, Number, Array, or Object
* - `default` Default value for this argument
*
* @param {String} name
* @param {Object} config
* @param {String} name - Argument name
* @param {Object} config - Argument options
* @param {any} config.type - String, Number, Array, or Object
* @param {string} [config.description] - Description for the argument
* @param {boolean} [config.required] - required` Boolean whether it is required
* @param {boolean} [config.optional] - Boolean whether it is optional
* @param {any} [config.default] - Default value for this argument
* @return {this} This generator
*/
argument(name, config) {
config = config || {};
Expand Down Expand Up @@ -870,11 +866,11 @@ class Generator extends EventEmitter {

/**
* Join a path to the source root.
* @param {...String} path
* @param {...String} dest - path parts
* @return {String} joined path
*/
templatePath() {
let filepath = path.join.apply(path, arguments);
templatePath(...dest) {
let filepath = path.join.apply(path, dest);

if (!path.isAbsolute(filepath)) {
filepath = path.join(this.sourceRoot(), filepath);
Expand All @@ -885,11 +881,11 @@ class Generator extends EventEmitter {

/**
* Join a path to the destination root.
* @param {...String} path
* @param {...String} dest - path parts
* @return {String} joined path
*/
destinationPath() {
let filepath = path.join.apply(path, arguments);
destinationPath(...dest) {
let filepath = path.join.apply(path, dest);

if (!path.isAbsolute(filepath)) {
filepath = path.join(this.destinationRoot(), filepath);
Expand Down Expand Up @@ -925,9 +921,9 @@ class Generator extends EventEmitter {
*
* Most usually, these transform stream will be Gulp plugins.
*
* @param {stream.Transform|stream.Transform[]} stream An array of Transform stream
* @param {stream.Transform|stream.Transform[]} streams An array of Transform stream
* or a single one.
* @return {this}
* @return {this} This generator
*/
registerTransformStream(streams) {
assert(streams, 'expected to receive a transform stream as parameter');
Expand Down

0 comments on commit ccbcc26

Please sign in to comment.