storybook-addon-jsdoc-to-mdx
Version:
Storybook addon that automatically generates MDX documentation from JSDoc comments in your TypeScript and JavaScript files. Supports HTML tags in comments, complex TypeScript types, and integrates seamlessly with Storybook 7.x and 8.x.
253 lines (252 loc) • 10.6 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const utils_1 = require("./utils");
// This test file will NOT test extractMethodFromCode directly to avoid TypeScript mocking issues
// Instead, we'll test it indirectly through the mdxContent tests
describe("removeCommentsFromCode", () => {
it("should remove comments from code", () => {
const code = `// this is a comment\nconst a = 5;`;
expect((0, utils_1.removeCommentsFromCode)(code)).toBe(`const a = 5;\n`);
});
it("should handle code without comments", () => {
const code = `const a = 5;`;
expect((0, utils_1.removeCommentsFromCode)(code)).toBe(`const a = 5;\n`);
});
});
describe("findBasePath", () => {
it("should find the base path", () => {
const filePath = "/user/local/src/app.ts";
const folderPaths = ["/user/local", "/user/src"];
expect((0, utils_1.findBasePath)(filePath, folderPaths)).toBe("/user/local");
});
it("should return empty string if no base path is found", () => {
const filePath = "/user/local/src/app.ts";
const folderPaths = ["/home", "/app"];
expect((0, utils_1.findBasePath)(filePath, folderPaths)).toBe("");
});
});
describe("getPathName", () => {
it("should return the correct path for a regular file", () => {
const filePath = "/user/local/src/utils.ts";
const baseDir = "/user/local/src";
expect((0, utils_1.getPathName)(filePath, baseDir)).toBe("utils");
});
it("should handle the index.ts file correctly", () => {
const filePath = "/user/local/src/index.ts";
const baseDir = "/user/local";
expect((0, utils_1.getPathName)(filePath, baseDir)).toBe("src");
});
it("should handle different base directories correctly", () => {
const filePath = "/user/local/src/utils.ts";
const baseDir = "/user";
expect((0, utils_1.getPathName)(filePath, baseDir)).toBe("local/src/utils");
});
});
// We'll test extractMethodFromCode indirectly through mdxContent.test.ts
describe("formatJsDocComment", () => {
it("should format a simple JSDoc comment", () => {
const comment = `
/**
* Simple description.
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toBe("> Simple description.");
});
it("should handle JSDoc comments with tags", () => {
const comment = `
/**
* Description with tags.
* @param {string} param1 - an example parameter.
* @returns {number} - example return value.
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Description with tags.");
expect(result).toContain("#### Parameter:");
expect(result).toContain("- `param1` *string* — an example parameter.");
expect(result).toContain("#### Returns:");
expect(result).toContain("`number` example return value.");
});
// Testing both @return and @returns tags (line 102)
it("should handle both @return and @returns tags", () => {
const comment = `
/**
* Function with return tag.
* @return {string} Return value
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with return tag.");
expect(result).toContain("#### Returns:");
expect(result).toContain("`string`");
});
it("should handle comments with extra spaces and lines", () => {
const comment = `
/**
*
* Description with extra spaces and lines.
*
* @param {string} param1
*
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Description with extra spaces and lines.");
expect(result).toContain("#### Parameter:");
expect(result).toContain("- `param1` *string* —");
});
it("should handle empty JSDoc comments", () => {
const comment = `/** */`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toBe(">"); // Empty JSDoc comment yields empty block-quote
});
it("should handle JSDoc comments without tags", () => {
const comment = `
/**
* Only a description.
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toBe("> Only a description.");
});
it("should handle JSDoc comments with only tags", () => {
const comment = `
/**
* @param {string} param1
* @returns {number}
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain(">"); // Block-quote with empty description
expect(result).toContain("#### Parameter:");
expect(result).toContain("- `param1` *string* —");
expect(result).toContain("#### Returns:");
});
it("should return raw text for non-JSDoc comments", () => {
const comment = "This is a normal comment, not JSDoc";
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toBe(comment);
});
it("should handle @example tags correctly", () => {
const comment = `
/**
* Function with example.
* @example
* // This is how you use it
* const result = myFunction();
* console.log(result);
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with example.");
expect(result).toContain("#### Example:");
expect(result).toContain("```ts");
// The exact content will depend on how comment-parser processes the example
});
// Test for example tag without source tokens (line 113-123)
it("should handle @example tags with just description", () => {
const comment = `
/**
* Function with example.
* @example Just a simple example without code blocks
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with example.");
expect(result).toContain("#### Example:");
expect(result).toContain("```ts");
// The implementation likely processes the description differently than expected
// Check for part of the description that would definitely appear
expect(result).toContain("simple example");
});
// Test for empty example tag (source will be empty)
it("should handle empty @example tags", () => {
const comment = `
/**
* Function with empty example.
* @example
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with empty example.");
expect(result).toContain("#### Example:");
});
it("should handle multiple @param tags", () => {
const comment = `
/**
* Multi-parameter function.
* @param {string} name - User name
* @param {number} age - User age
* @param {boolean} active - Active status
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
// Check with escaped hyphen due to the implementation in escapeHtmlTags
expect(result).toContain("> Multi\\-parameter function.");
expect(result).toContain("#### Parameter:");
expect(result).toContain("- `name` *string* — User name");
expect(result).toContain("- `age` *number* — User age");
expect(result).toContain("- `active` *boolean* — Active status");
});
it("should handle custom tags", () => {
const comment = `
/**
* Function with custom tags.
* @category Authentication
* @since v1.0.0
* @deprecated Use newFunction instead
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
// Check with escaped hyphen characters in the output
expect(result).toContain("> Function with custom tags.");
expect(result).toContain("#### Category:");
// The actual formatting includes a bullet list with tag values
expect(result).toContain("Authentication");
expect(result).toContain("#### Since:");
expect(result).toContain("v1.0.0");
expect(result).toContain("#### Deprecated:");
// The 'Use' part is included in the bullet list structure
expect(result).toContain("newFunction instead");
});
// Test custom tags with names and types (lines 139-143)
it("should handle custom tags with name and type", () => {
const comment = `
/**
* Function with named custom tags.
* @requires {module} path - Node.js path module
* @throws {Error} When input is invalid
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with named custom tags.");
expect(result).toContain("#### Requires:");
expect(result).toContain("- `path` *module* —");
expect(result).toContain("#### Throws:");
// The implementation might parse the tag differently
// Check for fragments that should definitely be present
expect(result).toContain("*Error*");
expect(result).toContain("input is invalid");
});
it("should escape HTML and special markdown characters", () => {
const comment = `
/**
* Function with <html> tags and {curly} braces.
* @param {Object} config - Config with <special> chars
*/
`;
const result = (0, utils_1.formatJsDocComment)(comment);
expect(result).toContain("> Function with <html> tags and \\{curly\\} braces.");
expect(result).toContain("*Object*");
expect(result).toContain("Config with <special> chars");
});
// Test handling of JSDoc with empty parse result (line 76)
it("should handle JSDoc with problematic parsing", () => {
// Mock a JSDoc comment that might not parse correctly
const comment = `/** @weird-tag */`;
const result = (0, utils_1.formatJsDocComment)(comment);
// Still produces a formatted result with blockquote
expect(result).toContain(">");
});
});