feat: add JSDoc to parser

Add JSDoc to parser

Closes #123

src/argumentsFill.js

@@ -1,3 +1,8 @@
+/**
+ * Set argument names and determine whether argument is flag
+ * @param {string} section - one argument from Options without description
+ * @param {object} argument - template of argument
+ */
 const setArgument = (section, argument) => {
     const argumentPrefix = /^-*/i;
 
@@ -17,6 +22,12 @@ const setArgument = (section, argument) => {
     });
 };
 
+/**
+ * Set argument description and default value
+ * @param {string} section - one argument from Options with only description
+ * @param {object} argument - template of argument
+ * @param {object} context - internal config
+ */
 const setDescription = (section, argument, context) => {
     argument.description = section;
     const regularExp = new RegExp(context.regexp.defaultValue, 'gim');
@@ -27,12 +38,18 @@ const setDescription = (section, argument, context) => {
     }
 };
 
+/**
+ * Remove extra characters from argument name
+ * @param {string} args - one argument without description
+ * @return {string} args - argument without extra characters
+ */
 const removeExtraCharacters = (args) => {
     args = args.replace(/=/g, ' ');
     args = args.replace(/,/g, ' ');
     return args;
 };
 
+// Export functions
 exports = module.exports = {
     setArgument, setDescription,
 };

src/configValidation.js

@@ -1,13 +1,26 @@
+// Import templates
 const configSchema = require('./template/configSchema.json');
 const configDefault = require('./template/configDefault.json');
+
+// Import npm package
 const validate = require('jsonschema').validate;
 
+/**
+ * Validate and fill with defaults configuration
+ * @param {object} config - user configuration
+ * @return {object} - validated configuration
+ */
 const configValidation = (config) => {
     schemaValidating(config);
     fillingWithDefaults(configDefault, config);
     return config;
 };
 
+/**
+ * Validate configuration by JSON-Schema
+ * @param {object} config - user configuration
+ * @throws {error} - if config doesn't match schema
+ */
 const schemaValidating = (config) => {
     const validatingResult = validate(config, configSchema).errors;
 
@@ -17,6 +30,11 @@ const schemaValidating = (config) => {
     }
 };
 
+/**
+ * Fill missing configuration fields with defaults
+ * @param {object} defaults - default configuration
+ * @param {object} config - user configuration
+ */
 const fillingWithDefaults = (defaults, config) => {
     Object.keys(defaults).forEach((key) => {
         config[key] =
@@ -26,4 +44,5 @@ const fillingWithDefaults = (defaults, config) => {
     });
 };
 
+// Export function
 module.exports = configValidation;

src/getContext.js

@@ -1,8 +1,17 @@
 'use strict';
 
+// Import template
 const argumentTemplate = require('./template/argument.json');
+
+// Import internal config
 const context = require('./template/context.js');
 
+/**
+ * Parse whole documentation and fill context
+ * @param {string} help - documentation of cli
+ * @param {object} config - user config of parser
+ * @return {object} context - internal config with parsed documentation
+ */
 const getContext = (help, config) => {
     try {
         context.options = [];
@@ -43,6 +52,13 @@ const getContext = (help, config) => {
     }
 };
 
+/**
+ * Search for all sections with given name in documentation and return it
+ * @param {string} sectionName - name of section
+ * @param {string} help - documentation of cli
+ * @param {object} context - internal config
+ * @return {array} - found sections
+ */
 const findSection = (sectionName, help, context) => {
     try {
         const regularExp = new RegExp(context.regexp.findSection.start +
@@ -54,6 +70,16 @@ const findSection = (sectionName, help, context) => {
     }
 };
 
+/**
+ * Searches for section by name, validate it and adds it to data
+ * If no sections found - use postfixes
+ * @param {string} name - name of section from user config
+ * @param {array} data - data from context where all found sections are added
+ * @param {string} help - documentation of cli
+ * @param {object} context - internal config
+ * @param {object} configSection - section from user configuration
+ * @return {array} data - data from context where all found sections are added
+ */
 const setSectionByNames = (name, data, help, context, configSection) => {
     let section = findSection(name, help, context);
     return validateSection(section) ? data.concat(section) :
@@ -64,10 +90,24 @@ const setSectionByNames = (name, data, help, context, configSection) => {
                     name, help, context, configSection.postfix, data);
 };
 
+/**
+ * Check if found section contains text
+ * @param {string} section - found section
+ * @return {boolean} - is section valid
+ */
 const validateSection = (section) => {
         return section.length > 0;
 };
 
+/**
+ * Searches for section by name + all postfixes and adds it to data [Postfix is array]
+ * @param {string} name - name of section
+ * @param {string} help - documentation of cli
+ * @param {object} context - internal config
+ * @param {object} configSection - section from user configuration
+ * @param {array} data - data from context where all found sections are added
+ * @return {array} data - data from context where all found sections are added
+ */
 const setSectionWithPostfixArray =
     (name, help, context, configSection, data) => {
     for (let postfix of configSection.postfix) {
@@ -79,9 +119,19 @@ const setSectionWithPostfixArray =
     return data;
 };
 
+/**
+ * Searches for section by name + postfix and adds it to data [Postfix is string]
+ * @param {string} name - name of section
+ * @param {string} help - documentation of cli
+ * @param {object} context - internal config
+ * @param {object} postfix - postfix for name from user configuration
+ * @param {array} data - data from context where all found sections are added
+ * @return {array} data - data from context where all found sections are added
+ */
 const setSectionWithPostfixSingle = (name, help, context, postfix, data) => {
     let section = findSection(name + postfix, help, context);
     return validateSection(section) ? data.concat(section) : data;
 };
 
+// Export function
 module.exports = getContext;

src/parseSection.js

@@ -1,5 +1,12 @@
+// Import functions
 const argumentsFill = require('./argumentsFill.js');
 
+/**
+ * Parse section Options and add arguments to context
+ * @param {string} section - section Options
+ * @param {object} context - internal config
+ * @param {object} argumentTemplate - template of parsed argument
+ */
 const options = (section, context, argumentTemplate) => {
     try {
         splitSection(section).forEach((option) => {
@@ -27,15 +34,27 @@ const options = (section, context, argumentTemplate) => {
     }
 };
 
+/**
+ * Parse section Usage and add argument "path" to context
+ * @param {string} section - section Usage
+ * @param {object} context - internal config
+ * @param {object} argumentTemplate - template of parsed argument
+ */
 const usage = (section, context, argumentTemplate) => {
     let argument = Object.assign({}, argumentTemplate);
     argument.longName = '';
+    argument.description = 'Path to file or folder to analyze';
     const regularExp = new RegExp(context.regexp.filePath, 'gi');
     if (section.match(regularExp)) {
         context.options.push(argument);
     }
 };
 
+/**
+ * Parse section Examples and set delimiter in context
+ * @param {string} section - section Usage
+ * @param {object} context - internal config
+ */
 const examples = (section, context) => {
     const delimitersTemplate = [' ', '='];
     delimitersTemplate.forEach((delimiter) => {
@@ -45,6 +64,11 @@ const examples = (section, context) => {
     });
 };
 
+/**
+ * Split section Options for array of arguments (argument + decription)
+ * @param {string} section - section Options
+ * @return {Array} - arguments from Options
+ */
 const splitSection = (section) => {
     try {
         let result = [];
@@ -68,6 +92,7 @@ const splitSection = (section) => {
     }
 };
 
+// Export functions
 exports = module.exports = {
     options: options,
     usage: usage,

src/parser.js

@@ -1,16 +1,29 @@
 'use strict';
 
+// Import functions
 const getContext = require('./getContext.js');
 const templatizer = require('./templatizer.js');
 const validate = require('./configValidation.js');
+
+// Import template
 const configDefault = require('./template/configDefault.json');
+
+// Create error if no docs passed
 const noDocsError = new Error('No documentation passed');
 
+/**
+ * Do parsing of documentation and return JSON-Schema with result of parsing
+ * @param {string} doc - documentation of cli
+ * @param {object} config - user config of parser
+ * @throws {error} - if no documentation passed
+ * @return {object} context - internal config with parsed documentation
+ */
 const parser = (doc, config) => {
     const configValidated = config ? validate(config) : configDefault;
     if (!doc) throw noDocsError;
     const context = getContext(doc, configValidated);
     return templatizer(context, configValidated);
 };
 
+// Export function
 module.exports = parser;

src/template/context.js

@@ -1,5 +1,7 @@
+// Import function
 const parseSection = require('./../parseSection.js');
 
+// Internal configuration with parsed arguments
 const context = {
     section: {
         options: {

src/templatizer.js

@@ -1,8 +1,18 @@
 'use strict';
+
+// Import module
 const fs = require('fs');
+
+// Import templates
 const argumentsTemplate = JSON.parse(fs.readFileSync('./src/template/args.json'));
 const optionTemplate = require('./template/option.json');
 
+/**
+ * Fill template schema with parsed arguments and return it
+ * @param {object} context - internal config with parsed arguments
+ * @param {object} config - user config
+ * @return {object} - filled template schema with parsed arguments
+ */
 const templatizer = (context, config) => {
     argumentsTemplate.definitions.arguments.properties = {};
     let result = argumentsTemplate;
@@ -50,4 +60,5 @@ const templatizer = (context, config) => {
     return result;
 };
 
+// Export function
 module.exports = templatizer;