jsdoc-builder 0.0.1

package/README.MD

@@ -0,0 +1,105 @@
+# JSDoc Builder
+
+JSDoc Builder is a CLI tool for automatically generating JSDoc comments for JavaScript and TypeScript files. It parses functions and variables to infer parameter types, return types, and descriptions, and then inserts JSDoc comments directly into the source code.
+
+## Features
+
+- Automatically generates JSDoc comments for:
+  - Function declarations
+  - Arrow functions
+  - TypeScript types and interfaces
+- Infers parameter and return types from TypeScript annotations.
+- Outputs clean and structured JSDoc comments.
+
+## Installation
+
+Install the library globally or locally via npm:
+
+```bash
+npm install jsdoc-builder -g
+```
+
+or
+
+```bash
+npm install jsdoc-builder --save-dev
+```
+
+## Usage
+
+### CLI Command
+
+Run the following command to generate JSDoc comments for a file:
+
+```bash
+jsdoc-builder <file-path>
+```
+
+Replace `<file-path>` with the path to the JavaScript or TypeScript file you want to process.
+
+### Example
+
+#### Input File (`example.ts`):
+
+```typescript
+function add(a: number, b: number) {
+  return a + b;
+}
+
+const multiply = (a: number, b: number): number => {
+  return a * b;
+};
+```
+
+#### Command:
+
+```bash
+jsdoc-builder example.ts
+```
+
+#### Output File (`example.ts`):
+
+```typescript
+/**
+ * @description Function add
+ * @param {number} a
+ * @param {number} b
+ * @returns {void}
+ */
+function add(a: number, b: number) {
+  return a + b;
+}
+
+/**
+ * @description Function multiply
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+const multiply = (a: number, b: number): number => {
+  return a * b;
+};
+```
+
+## API
+
+### `generateJSDoc(filePath: string): void`
+
+- **Description**: Processes the specified file to add JSDoc comments.
+- **Parameters**:
+  - `filePath` (string): The path to the file to be processed.
+- **Returns**: `void`
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch: `git checkout -b feature-name`.
+3. Commit your changes: `git commit -m 'Add feature-name'`.
+4. Push to the branch: `git push origin feature-name`.
+5. Submit a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const index_1 = require("./index");
+commander_1.program
+    .argument("<file>", "The TypeScript or JavaScript file to process")
+    .description("Generate JSDoc comments for the given TypeScript or JavaScript file")
+    .action((file) => {
+    (0, index_1.generateJSDoc)(file);
+});
+commander_1.program.parse(process.argv);

package/dist/example/example.js

@@ -0,0 +1,2 @@
+"use strict";
+const multiply = ({ x, y }) => x * y;

package/dist/generate.js

@@ -0,0 +1,37 @@
+import ts from "typescript";
+import fs from "fs";
+export function generateJSDoc(filePath) {
+    const fileContent = fs.readFileSync(filePath, "utf-8");
+    const sourceFile = ts.createSourceFile(filePath, fileContent, ts.ScriptTarget.Latest);
+    const functions = [];
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isArrowFunction(node)) {
+            const functionName = node.name?.text || "Anonymous";
+            const params = node.parameters
+                .map((param) => {
+                const paramName = param.name?.getText(sourceFile) || "unknown";
+                const paramType = param.type ? param.type.getText(sourceFile) : "any";
+                return `@param {${paramType}} ${paramName}`;
+            })
+                .join("\n");
+            const returnType = node.type
+                ? `@returns {${node.type.getText(sourceFile)}}`
+                : "@returns {any}";
+            const jsDoc = `
+/**
+ * @function ${functionName}
+ * ${params}
+ * ${returnType}
+ */
+      `;
+            functions.push(jsDoc);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    // JSDoc을 원본 파일 상단에 삽입
+    const updatedContent = functions.join("\n") + "\n\n" + fileContent;
+    fs.writeFileSync(filePath, updatedContent, "utf-8");
+}

package/dist/index.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateJSDoc = void 0;
+const ts = require("typescript");
+const fs = require("fs");
+/**
+ * Parses a TypeScript or JavaScript file and adds JSDoc comments to functions.
+ * @param filePath - The path of the file to process.
+ */
+function generateJSDoc(filePath) {
+    const sourceCode = fs.readFileSync(filePath, "utf-8");
+    const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true);
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const jsDoc = createJSDoc(node.name.text, node.parameters, node.type);
+            ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, jsDoc.comment, true);
+            return node;
+        }
+        // Check for arrow functions assigned to a constant
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isArrowFunction(node.initializer)) {
+            const jsDoc = createJSDoc(node.name.getText(), node.initializer.parameters, node.initializer.type);
+            // Add JSDoc to the entire variable statement for clarity
+            const parent = node.parent;
+            if (ts.isVariableDeclarationList(parent) &&
+                parent.declarations.length === 1) {
+                ts.addSyntheticLeadingComment(parent.parent, ts.SyntaxKind.MultiLineCommentTrivia, jsDoc.comment, true);
+            }
+            return node;
+        }
+        return ts.visitEachChild(node, visit, context);
+    }
+    // Create a transformation context
+    const context = {
+        factory: ts.factory,
+        startLexicalEnvironment: () => { },
+        endLexicalEnvironment: () => [],
+        suspendLexicalEnvironment: () => { },
+        resumeLexicalEnvironment: () => { },
+        requestEmitHelper: () => { },
+        readEmitHelpers: () => undefined,
+        enableSubstitution: () => { },
+        isSubstitutionEnabled: () => false,
+        onSubstituteNode: (hint, node) => node,
+        enableEmitNotification: () => { },
+        isEmitNotificationEnabled: () => false,
+        onEmitNode: (hint, node, emitCallback) => emitCallback(hint, node),
+        getCompilerOptions: () => ({}),
+        hoistFunctionDeclaration: () => { },
+        hoistVariableDeclaration: () => { },
+    };
+    const result = ts.transform(sourceFile, [
+        (context) => (rootNode) => ts.visitNode(rootNode, visit),
+    ]);
+    const transformedSourceFile = result.transformed[0];
+    const updatedCode = printer.printFile(transformedSourceFile);
+    fs.writeFileSync(filePath, updatedCode, "utf-8");
+}
+exports.generateJSDoc = generateJSDoc;
+/**
+ * Creates a JSDoc comment.
+ * @param functionName - The name of the function.
+ * @param parameters - The parameters of the function.
+ * @param returnType - The return type of the function.
+ * @returns A JSDoc comment as a string.
+ */
+function createJSDoc(functionName, parameters, returnType) {
+    const paramTags = parameters.map((param) => ({
+        tagName: "param",
+        name: param.name.getText(),
+        type: param.type ? param.type.getText() : "any",
+    }));
+    const returnTag = {
+        tagName: "returns",
+        type: returnType ? returnType.getText() : "void",
+    };
+    const commentText = [
+        `* @description Press Your { Function ${functionName} } Description`,
+        ...paramTags.map((tag) => `* @param {${tag.type}} ${tag.name}`),
+        `* @returns {${returnTag.type}}`,
+    ].join("\n");
+    return { comment: `*\n${commentText}\n` };
+}

package/dist/parse.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateJSDoc = void 0;
+const fs = require("fs");
+const ts = require("typescript");
+function generateJSDoc(filePath) {
+    const fileContent = fs.readFileSync(filePath, "utf-8");
+    const sourceFile = ts.createSourceFile(filePath, fileContent, ts.ScriptTarget.Latest, true);
+    // Example: Traverse the AST and insert JSDoc
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const functionName = node.name.text;
+            console.log(`Found function: ${functionName}`);
+            // Add logic to generate JSDoc comments
+        }
+    });
+    // Save the updated file (placeholder)
+    console.log(`Generated JSDoc for: ${filePath}`);
+}
+exports.generateJSDoc = generateJSDoc;

package/dist/parser.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFile = void 0;
+const ts = require("typescript");
+/**
+ * Parse a TypeScript or JavaScript file to extract functions
+ * @param content File content
+ * @returns Array of FunctionInfo
+ */
+function parseFile(content) {
+    const sourceFile = ts.createSourceFile("temp.ts", content, ts.ScriptTarget.ESNext, true);
+    const functions = [];
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
+            const name = node.name ? node.name.text : "anonymous";
+            const params = node.parameters.map((param) => ({
+                name: param.name.getText(),
+                type: param.type ? param.type.getText() : "any",
+                description: "",
+            }));
+            const returns = {
+                type: node.type ? node.type.getText() : "void",
+                description: "",
+            };
+            functions.push({
+                name,
+                description: `Function ${name}`,
+                params,
+                returns,
+                start: node.pos,
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return functions;
+}
+exports.parseFile = parseFile;

package/dist/src/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const index_1 = require("./index");
+commander_1.program
+    .command("generate <file>")
+    .description("Generate JSDoc comments for the given TypeScript or JavaScript file")
+    .action((file) => {
+    (0, index_1.generateJSDoc)(file);
+});
+commander_1.program.parse(process.argv);

package/dist/src/index.js

@@ -0,0 +1,56 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateJSDoc = void 0;
+const fs = __importStar(require("fs"));
+const parser_1 = require("./parser");
+const utils_1 = require("./utils");
+const utils_2 = require("./utils");
+/**
+ * Main function to generate JSDoc for a file
+ * @param filePath Path to the file
+ */
+function generateJSDoc(filePath) {
+    if (!(0, utils_1.fileExists)(filePath)) {
+        console.error(`File not found: ${filePath}`);
+        return;
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const functions = (0, parser_1.parseFile)(content);
+    let updatedContent = content;
+    functions.forEach((func) => {
+        const jsdoc = (0, utils_2.formatJSDoc)(func.description, func.params, func.returns);
+        // 삽입할 위치 찾기
+        const insertPosition = func.start;
+        updatedContent =
+            updatedContent.slice(0, insertPosition) +
+                jsdoc +
+                "\n" +
+                updatedContent.slice(insertPosition);
+    });
+    (0, utils_1.writeFile)(filePath, updatedContent);
+    console.log(`JSDoc comments added to ${filePath}`);
+}
+exports.generateJSDoc = generateJSDoc;

package/dist/src/parser.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFile = void 0;
+const ts = __importStar(require("typescript"));
+/**
+ * Parse a TypeScript or JavaScript file to extract functions
+ * @param content File content
+ * @returns Array of FunctionInfo
+ */
+function parseFile(content) {
+    const sourceFile = ts.createSourceFile("temp.ts", content, ts.ScriptTarget.ESNext, true);
+    const functions = [];
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
+            const name = node.name ? node.name.text : "anonymous";
+            const params = node.parameters.map((param) => ({
+                name: param.name.getText(),
+                type: param.type ? param.type.getText() : "any",
+                description: "",
+            }));
+            const returns = {
+                type: node.type ? node.type.getText() : "void",
+                description: "",
+            };
+            functions.push({
+                name,
+                description: `Function ${name}`,
+                params,
+                returns,
+                start: node.pos,
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return functions;
+}
+exports.parseFile = parseFile;

package/dist/src/utils.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatJSDoc = exports.writeFile = exports.fileExists = void 0;
+const fs = __importStar(require("fs"));
+/**
+ * Check if the file exists
+ * @param filePath Path to the file
+ * @returns True if the file exists
+ */
+function fileExists(filePath) {
+    return fs.existsSync(filePath);
+}
+exports.fileExists = fileExists;
+/**
+ * Write content to a file
+ * @param filePath Path to the file
+ * @param content Content to write
+ */
+function writeFile(filePath, content) {
+    fs.writeFileSync(filePath, content, "utf-8");
+}
+exports.writeFile = writeFile;
+/**
+ * Format a JSDoc comment
+ * @param description Description of the function
+ * @param params Parameters of the function
+ * @param returns Return type of the function
+ * @returns Formatted JSDoc string
+ */
+function formatJSDoc(description, params, returns) {
+    const paramDocs = params
+        .map((param) => ` * @param {${param.type}} ${param.name} - ${param.description}`)
+        .join("\n");
+    const returnDoc = ` * @returns {${returns.type}} - ${returns.description}`;
+    return `/**
+ * ${description}
+${paramDocs}
+${returnDoc}
+ */`;
+}
+exports.formatJSDoc = formatJSDoc;

package/dist/utils.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatJSDoc = exports.writeFile = exports.fileExists = void 0;
+const fs = require("fs");
+/**
+ * Check if the file exists
+ * @param filePath Path to the file
+ * @returns True if the file exists
+ */
+function fileExists(filePath) {
+    return fs.existsSync(filePath);
+}
+exports.fileExists = fileExists;
+/**
+ * Write content to a file
+ * @param filePath Path to the file
+ * @param content Content to write
+ */
+function writeFile(filePath, content) {
+    fs.writeFileSync(filePath, content, "utf-8");
+}
+exports.writeFile = writeFile;
+/**
+ * Format a JSDoc comment
+ * @param description Description of the function
+ * @param params Parameters of the function
+ * @param returns Return type of the function
+ * @returns Formatted JSDoc string
+ */
+function formatJSDoc(description, params, returns) {
+    const paramDocs = params
+        .map((param) => ` * @param {${param.type}} ${param.name} - ${param.description}`)
+        .join("\n");
+    const returnDoc = ` * @returns {${returns.type}} - ${returns.description}`;
+    return `/**
+ * "vv"${description}
+${paramDocs}
+${returnDoc}
+ */`;
+}
+exports.formatJSDoc = formatJSDoc;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "jsdoc-builder",
+  "version": "0.0.1",
+  "author": "dori",
+  "description": "Generate JSDoc comments for JavaScript and TypeScript files.",
+  "bin": {
+    "jsdoc-builder": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "jsdoc-generator",
+    "jsdoc",
+    "typescript",
+    "javascript",
+    "documentation",
+    "cli",
+    "auto-jsdoc"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "test": "ts-node src/cli.ts"
+  },
+  "dependencies": {
+    "commander": "^10.0.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.0.0"
+  }
+}