@iviva/react-tsdoc 0.1.8 → 0.2.0

package/README.md

@@ -1,49 +1,240 @@
-# React Typescript Document Generator
-Documentation generator for React Components written in Typescript.
+# React TypeScript Document Generator
 
-This exists to generate docs for your react components.
+**React TypeScript Document Generator** is a command-line tool that helps you automatically generate **clear, well-structured documentation** and **type definitions** for your React components, hooks, and utility functions written in TypeScript.  
 
-It extracts documentation from your components and their props.
+It scans your code, reads **TSDoc-style comments**, and produces:
+- **Markdown documentation** with prop tables, examples, and type signatures.
+- **Type definition files** (`.d.ts`) for easy API sharing.
 
-## Usage
+Whether you’re building a reusable UI library or maintaining an internal component set, this tool saves you from writing documentation manually and keeps it consistent with your code.
 
-Use tsdoc-style comments for your components:
+---
 
+## Why Use This Tool?
+- **Stay in sync**: Documentation is generated directly from your source code.
+- **Easy to maintain**: Update your comments, re-run the tool, and everything stays current.
+- **Supports multiple React patterns**: Functional components, class components, hooks, and more.
+- **Clear output**: Easy-to-read Markdown for documentation sites and type definitions for developers.
+
+---
+
+## Installation
+
+Install globally via npm:
+
+```bash
+npm install -g react-tsdoc
+````
+
+---
+
+## How It Works
+
+1. **You write code with TSDoc comments** describing your components, props, hooks, or functions.
+2. **Run the CLI commands** to generate documentation and type definitions.
+3. **Share or publish** the generated docs and `.d.ts` files.
+
+---
+
+## Commands & Parameters
+
+The CLI provides two main commands:
+
+### 1. Generate Type Definitions
+
+```bash
+react-tsdoc types <path-to-root-ts> <output.d.ts> --module-name <module-name>
 ```
-/**
 
-*/
+**Purpose**: Creates a `.d.ts` type definition file for your public API.
+
+**Parameters**:
+
+* `<path-to-root-ts>` — Entry point TypeScript file (e.g., `src/index.ts`).
+* `<output.d.ts>` — Path to save the generated type definitions (e.g., `dist/types.d.ts`).
+* `--module-name <module-name>` — The name of your library/module (e.g., `my-lib`).
+
+---
+
+### 2. Generate Documentation
+
+```bash
+react-tsdoc docs <path-to-root-ts> <output-folder> --module-name <module-name>
 ```
 
-Your components must either be classes that inherit from `React.Component<P,S>` or, if you're using new-style function components,
-then they should be declared as variables of type `React.FunctionComponent<P>`.
+**Purpose**: Generates Markdown documentation in categorized folders (`components`, `hooks`, etc.).
+
+**Parameters**:
+
+* `<path-to-root-ts>` — Entry point TypeScript file.
+* `<output-folder>` — Folder to store generated Markdown files (e.g., `docs`).
+* `--module-name <module-name>` — Your library/module name.
+
+---
 
-Examples:
+## Supported Code Patterns
 
+The generator supports common React patterns and outputs clear documentation for each.
+
+### Functional Components
+
+Declared with `React.FC` or `React.FunctionComponent`.
+
+```typescript
+interface ILabelProps {
+  /** The label text to display */
+  value: string;
+}
+/**
+ * A simple label component
+ * @export
+ * @example <Label value="Hello" />
+ */
+const Label: React.FC<ILabelProps> = ({ value }) => <span>{value}</span>;
 ```
+---
+
+### Class Components
+
+Extend `React.Component` with props (and optional state).
+
+```typescript
 interface ILabelProps {
-    /**
-    *  the label text to be set
-    */
-    value: string;
+  /** The label text to display */
+  value: string;
+}
+/**
+ * A class-based label component
+ * @export
+ * @example <Label2 value="Hello" />
+ */
+class Label2 extends React.Component<ILabelProps> {
+  render() {
+    return <span>{this.props.value}</span>;
+  }
 }
+```
+---
 
+### ForwardRef Components
+
+Expose refs using `React.forwardRef`.
+
+```typescript
+interface IRef { focus(): void; }
+interface IInputProps { value: string; }
 /**
-* A simple component to render a static label
-*/
-const Label:React.Component<ILabelProps> = (props) =>  <span>{props.value}</span>;
+ * An input with ref support
+ * @export
+ * @example <Input ref={ref} value="Hello" />
+ */
+const Input = React.forwardRef<IRef, IInputProps>((props, ref) => (
+  <input ref={ref} value={props.value} />
+));
+```
+---
 
+### Memoized Components
 
+Use `React.memo` to optimize rendering.
+
+```typescript
+interface IMemoProps { value: string; }
 /**
-* A simple component to render a static label
-*/
-class Label2 extends React.Component<ILabelProps,{}> {
-    render() {
-        return <span>{this.props.value}</span>;
-    }
+ * A memoized label
+ * @export
+ * @example <MemoedLabel value="Hello" />
+ */
+const MemoLabel: React.FC<IMemoProps> = ({ value }) => <span>{value}</span>;
+const MemoedLabel = React.memo(MemoLabel);
+```
+---
+
+## Functions & Hooks
+
+### Functions
+
+Standalone utility functions.
+
+```typescript
+/**
+ * Adds two numbers
+ * @export
+ * @example add(2, 3) // Returns 5
+ */
+function add(a: number, b: number): number {
+  return a + b;
 }
 ```
+---
 
-## Commands
-react-tsdoc types <path-to-root-ts> <output.d.ts> --module-name <module-name>
+### Hooks
+
+Custom hooks starting with `use`.
+
+```typescript
+/**
+ * Fetches data from a URL
+ * @export
+ * @hook
+ * @example const data = useFetchData('url');
+ */
+function useFetchData(url: string): string {
+  return "data";
+}
+```
+---
+
+## Supported TSDoc Annotations
+
+| Tag        | Description                                                                               |
+| ---------- | ----------------------------------------------------------------------------------------- |
+| `@export`  | Marks the item for inclusion in docs and type definitions. Required for public API items. |
+| `@example` | Adds usage examples (supports multiple).                                                  |
+| `@hook`    | Optional for hooks; classifies them in generated docs.                                    |
+
+---
+
+## Example Workflow
+
+1. Document your code with TSDoc annotations.
+2. Generate type definitions:
+
+   ```bash
+   react-tsdoc types src/index.ts dist/types.d.ts --module-name my-ui
+   ```
+3. Generate documentation:
+
+   ```bash
+   react-tsdoc docs src/index.ts docs --module-name my-ui
+   ```
+
+---
+
+## Tips for Best Results
+
+* Write **clear, concise comments** for props, parameters, and return values.
+* Include **examples** that developers can copy and paste.
+* Keep your public API clean and well-annotated.
+
+---
+
+## Contributing
+
+We welcome contributions!
+Here’s how you can help:
+
+1. **Report issues** or suggest features on [GitHub](https://github.com/lucy-platform/react-tsdoc/issues).
+2. **Submit pull requests** with bug fixes or enhancements.
+3. Improve this documentation with clearer examples or new sections.
+
+Before contributing, please:
+
+* Fork the repository.
+* Create a new branch for your changes.
+* Ensure your code follows the existing coding style.
+* Add or update tests when applicable.
+
+---
 
+Happy documenting! 🚀

package/bin/react-tsdoc.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require('../dist/index').main();
+require('../dist/cli/index').main();

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function main(): void;

package/dist/cli/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = void 0;
+const commander_1 = require("commander");
+const index_1 = require("../index");
+const logger_1 = require("../utils/logger");
+function main() {
+    try {
+        commander_1.program
+            .name('react-tsdoc')
+            .description('Generate docs for React components')
+            .version('0.1.9');
+        commander_1.program
+            .command('types')
+            .description('Generate type definitions')
+            .argument('[input.ts]', 'Input TypeScript file')
+            .argument('[output.d.ts]', 'Output declaration file')
+            .option('--module-name <name>', 'Module name for type definitions')
+            .action((input, output, options) => {
+            (0, index_1.generateTypeDefinition)(input, output, options.moduleName);
+        });
+        commander_1.program
+            .command('docs')
+            .description('Generate Markdown documentation')
+            .argument('[input.ts]', 'Input TypeScript file')
+            .argument('[output-folder]', 'Output folder for documentation')
+            .option('--module-name <name>', 'Module name for documentation')
+            .action((input, output, options) => {
+            (0, index_1.generateDocs)(input, output, options.moduleName);
+        });
+        commander_1.program.parse(process.argv);
+    }
+    catch (e) {
+        (0, logger_1.logError)(e);
+    }
+}
+exports.main = main;
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;AAAA,yCAAoC;AACpC,oCAAgE;AAChE,4CAA2C;AAE3C,SAAgB,IAAI;IAChB,IAAI;QACA,mBAAO;aACF,IAAI,CAAC,aAAa,CAAC;aACnB,WAAW,CAAC,oCAAoC,CAAC;aACjD,OAAO,CAAC,OAAO,CAAC,CAAC;QAEtB,mBAAO;aACF,OAAO,CAAC,OAAO,CAAC;aAChB,WAAW,CAAC,2BAA2B,CAAC;aACxC,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;aAC/C,QAAQ,CAAC,eAAe,EAAE,yBAAyB,CAAC;aACpD,MAAM,CAAC,sBAAsB,EAAE,kCAAkC,CAAC;aAClE,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;YAC/B,IAAA,8BAAsB,EAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;QAEP,mBAAO;aACF,OAAO,CAAC,MAAM,CAAC;aACf,WAAW,CAAC,iCAAiC,CAAC;aAC9C,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAC;aAC/C,QAAQ,CAAC,iBAAiB,EAAE,iCAAiC,CAAC;aAC9D,MAAM,CAAC,sBAAsB,EAAE,+BAA+B,CAAC;aAC/D,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;YAC/B,IAAA,oBAAY,EAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;QAEP,mBAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B;IAAC,OAAO,CAAC,EAAE;QACR,IAAA,iBAAQ,EAAC,CAAC,CAAC,CAAC;KACf;AACL,CAAC;AA/BD,oBA+BC"}

package/dist/core/analyzer.d.ts

@@ -0,0 +1,18 @@
+import * as ts from 'typescript';
+import { IDocInfo, IReactComponent } from './types';
+export declare function extractComment(node: ts.Node): string;
+export declare function getCode(node: ts.Node): string;
+export declare function unwrapCallWrappers(expr: ts.Expression): {
+    inner: ts.Expression;
+    wrappers: string[];
+};
+export declare function analyzeComponentPattern(init: ts.Expression, name: string, comment: string, checker: ts.TypeChecker, docInfo: IDocInfo, declaredType?: ts.TypeNode): IReactComponent | null;
+export declare function parseInterfaceDeclaration(node: ts.Node, docInfo: IDocInfo): void;
+export declare function parseVariableDeclaration(node: ts.Node, docInfo: IDocInfo, checker: ts.TypeChecker): void;
+export declare function parseClassDeclaration(node: ts.Node, docInfo: IDocInfo, checker?: ts.TypeChecker): void;
+export declare function parseFunctionDeclaration(node: ts.Node, docInfo: IDocInfo, checker?: ts.TypeChecker): void;
+export declare function parseEnumDeclaration(node: ts.Node, docInfo: IDocInfo): void;
+export declare function parseTypeAlias(node: ts.Node, docInfo: IDocInfo): void;
+export declare function walkTree(node: ts.Node, docInfo: IDocInfo, checker: ts.TypeChecker): void;
+export declare function validateProgram(program: ts.Program): void;
+export declare function getSources(program: ts.Program): string[];