refactor: better docs

Author: araujogui

bin/cli.mjs

@@ -119,6 +119,4 @@ await runGenerators({
 
 linter.report(reporter);
 
-if (linter.hasError()) {
-  exit(1);
-}
+exit(Number(linter.hasError()));

src/linter/index.mjs

@@ -6,17 +6,21 @@ import { missingChangeVersion } from './rules/missing-change-version.mjs';
 import { missingIntroducedIn } from './rules/missing-introduced-in.mjs';
 
 /**
- * Lint issues in ApiDocMetadataEntry entries
+ * Creates a linter instance to validate ApiDocMetadataEntry entries
  *
  * @param {boolean} dryRun Whether to run the linter in dry-run mode
  */
 const createLinter = dryRun => {
   /**
+   * Lint issues found during validations
+   *
    * @type {Array<import('./types.d.ts').LintIssue>}
    */
   const issues = [];
 
   /**
+   * Lint rules to validate the entries against
+   *
    * @type {Array<import('./types.d.ts').LintRule>}
    */
   const rules = [
@@ -26,6 +30,8 @@ const createLinter = dryRun => {
   ];
 
   /**
+   * Validates a ApiDocMetadataEntry entry against all defined rules
+   *
    * @param {ApiDocMetadataEntry} entry
    * @returns {void}
    */
@@ -40,6 +46,8 @@ const createLinter = dryRun => {
   };
 
   /**
+   * Validates an array of ApiDocMetadataEntry entries against all defined rules
+   *
    * @param {ApiDocMetadataEntry[]} entries
    * @returns {void}
    */
@@ -50,7 +58,10 @@ const createLinter = dryRun => {
   };
 
   /**
-   * @param {keyof reporters} reporterName
+   * Reports found issues using the specified reporter
+   *
+   * @param {keyof typeof reporters} reporterName Reporter name
+   * @returns {void}
    */
   const report = reporterName => {
     if (dryRun) {
@@ -65,7 +76,7 @@ const createLinter = dryRun => {
   };
 
   /**
-   * Returns whether there are any issues with a level of 'error'
+   * Checks if any error-level issues were found during linting
    *
    * @returns {boolean}
    */

src/linter/reporters/console.mjs

@@ -12,6 +12,8 @@ const levelToColorMap = {
 };
 
 /**
+ * Console reporter
+ *
  * @type {import('../types.d.ts').Reporter}
  */
 export default issue => {

src/linter/reporters/github.mjs

@@ -9,7 +9,7 @@ const actions = {
 };
 
 /**
- * GitHub action reporter for
+ * GitHub actions reporter
  *
  * @type {import('../types.d.ts').Reporter}
  */

src/linter/rules/invalid-change-version.mjs

@@ -2,7 +2,7 @@ import { LINT_MESSAGES } from '../../constants.mjs';
 import { validateVersion } from '../utils/semver.mjs';
 
 /**
- * Checks if any change version is invalid.
+ * Checks if any change version is invalid
  *
  * @param {ApiDocMetadataEntry} entry
  * @returns {Array<import('../types').LintIssue>}

src/linter/rules/missing-change-version.mjs

@@ -1,5 +1,5 @@
 /**
- * Checks if any change version is missing.
+ * Checks if any change version is missing
  *
  * @param {ApiDocMetadataEntry} entry
  * @returns {Array<import('../types').LintIssue>}

src/linter/rules/missing-introduced-in.mjs

@@ -1,7 +1,7 @@
 import { LINT_MESSAGES } from '../../constants.mjs';
 
 /**
- * Checks if `introduced_in` field is missing in the API doc entry.
+ * Checks if `introduced_in` field is missing
  *
  * @param {ApiDocMetadataEntry} entry
  * @returns {Array<import('../types.d.ts').LintIssue>}

src/linter/utils/semver.mjs

@@ -2,6 +2,7 @@
  * Validates a semver version string
  *
  * @param {string} version
+ * @returns {boolean}
  */
 export const validateVersion = version => {
   // https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string