background

Department A uses ReactNative development to maintain RN component library, while Department B uses native development. One day, to cope with rapid business iteration, students in Department B also need to access RN. Which brings us to the following question

Students from Section B want to know:

  • A What functions does the component library support
  • How are components of A component library used

Problems of component inventory in Department A:

  • No documentation (there was, iteration was too fast, documentation was too cumbersome, and became obsolete over time)
  • Note less, for a long time, the original development of the students have resigned, want to figure out the component support functions have to look at the source code

Student A needs to support student B frequently, which is troublesome and does not want to spend too much time writing documents. In order to solve this problem, refer to the native development used Java Doc tools, and finally found this – TypeDoc, use down to experience the line, than every time the source convenient, write an article to share this tool

Click to see a sample effect

TypeDoc converts comments in TypeScript source code into rendered HTML documents or JSON models. It is extensible and supports multiple configurations.

Initialization engineering

Create a new TS React application to demonstrate the functionality

npm install -g create-react-app
create-react-app type-doc-demo --template typescript
Copy the code

Install typeDoc

npm install typedoc --save-dev
Copy the code

Engineering instructions

The directory structure for component projects is shown below

. ├ ─ ─ components │ ├ ─ ─ Card │ │ └ ─ ─ index. The TSX │ ├ ─ ─ Filter │ │ └ ─ ─ index. The TSX │ └ ─ ─ index. The TSX ├ ─ ─ demo │ └ ─ ─ Filter. The TSX ├ ─ ─ App. The TSX...Copy the code

Components /index.tsx exports all components, and the demo directory contains sample code.

// components/index.tsx
export { Card } from "./Card";
export type { CardProps } from "./Card";
export { Filter } from "./Filter";
export type { FilterProps } from "./Filter";
Copy the code

Basis function

Create a TypeDoc.js file in the project root directory, specifying the entry file and output directory

// typedoc.js
module.exports = {
  entryPoints: ["./src/components/index.tsx"].out: "doc".name: Component library};Copy the code

Package. json add script packaging to see the effect

// package.json."scripts": {
    "doc": "typedoc --tsconfig tsconfig.json --options typedoc.js"},...Copy the code

NPM run doc will look like this, and the readme.md content will be placed on the home page by default

MarkDown grammar

TypeDoc will generate documentation through comments on the exported content, which support MarkDown syntax, so you can write comments like this

  • Insert table
export type FilterProps = {
    / * * * * * | popup window type drop | fullscreen | | * : - : | : - : drop-down | full screen | | | * * * /modalMode? :"dorp" | "fullscreen";
};
Copy the code
  • Insert sample code
export type FilterProps = {
  Configuration / * * * * ` ` ` * {* base_filter: {* checkBox:} {* columns: 4, * and *}, *} * ` ` ` * /config? :object;
};
Copy the code

Generate document effect

Insert a custom resource

Add the following configuration to typedoc.js

// typedoc.js
module.exports = {
  ...
  media: ["./demo-images"].includes: ["./src/demo"]};Copy the code
  • includes: directory that contains files that can[[include:file.md]]Injection into the generated document in document comments.
  • media: Specifies the media directory to copy to the output file. The media canmedia://file.jpgLink to in the documentation comments

After the above configuration is added, the corresponding resources can be accessed in comments in the following way

/ * * * * # # # Filter figure * < img SRC = "media: / / Filter. JPG" width = "50%" / > * *@see [] data format specification document (https://www.baidu.com) * * * # # # # # code examples use the * ` ` ` * [[include: Filter. The TSX]] * ` ` ` * * /
export const Filter: React.FC<FilterProps> = () = >{... };Copy the code

The resulting document looks like this

The result is a simple development document with minimal effort, providing code samples, feature sample diagrams, and property descriptions that are convenient for internal use only.

Other configuration

The configuration file

You can add the following configuration to the typedoc.js file

module.exports = {
  excludePrivate: true.// The export does not contain the private declaration content
  excludeProtected: true.// The export does not contain protected declared content
  // Add package version to project name. In this case, if the project is based on version 1.2.3 'package.json', this will generate a document named 'name-v1.2.3'
  includeVersion: true};Copy the code

Comment tags

  • @ignore: The document ignores this module
  • @category: Groups the content together with the tag

A link to the

  • Typedoc Official document: typedoc.org/guides/inst…
  • IO/TypeDoc-dem… i2333g3.giee. IO/Typedoc-dem…
  • This article demo project: gitee.com/i2333g3/typ…