easy-typescript-documentation v1.0.3

Easy-typescript-documentation

Generate documentation based on your typescript classes.
I created this package because I had difficulties using tsdoc for my basic needs.

Check out typescirpt-rest if you want to generate documentation for your API.
If you need more functionnalities check out tsdoc.

The packages provides some pre-defined annotations, and functions to create your owns.

You can check the documentation (Generated with the getDocPage function).
If you don't like the look, feel free to create your own layout based on the json generated by the getJson functions.

Github Repository.

Support for methods is coming. (probably soon)

Quick Start

npm i --save typescript easy-typescript-documentation

Set "experimentalDecorators": true and "target": "ES2017" or above in tsconfig.json

model.ts

import {Doc, ClassName, ClassDesc, Name, Desc, Color, DOC_COLOR, Note} from "easy-typescript-documentation"

@Doc
@ClassName("My Object")
@ClassDesc("Object with a name, a setter and a getter.")
class myObject {

    constructor(name: string) {
        this.name = name;
    }

    @Name("Name")
    @Desc("This is a description")
    @Color(DOC_COLOR.ORANGE)
    @Note("This is a note")
    name: string;

}

doc.ts

import * as model from "./model"
import { getDocPage, getJson } from "easy-typescript-documentation"

//Returns a list of object representing each class with the @Doc decorator in model.ts
//You can use it to build your own UI. More infos in JSON structure
const json = getJson(model)

//Return an html page as a string that you can return from your api
const name = "My documentation"
const description = "Exemple documentation"
const htmlPage = getDocPage(name, model, description)

Here is the resulting htlm page with some more classes in model.ts

JSON structure

The function getJson returns a liste containing all classes in the object passed to it.
The objects follow this pattern.

{
    name: "name",       //If using @ClassName
    description: ""     //If using @ClassDesc
    //...Other custom class decorators

    //Annotated properties
    properties : [{
        key: "key",                     //key of the propertie
        type: "string"                  //Typescript type
        name: "name",                   //If using @Name
        description: "description",     //If using @Desc
        color: "red",                   //If using @Color
        note : "note"                   //If using @Note
        //...Other custom propertie decorators
    },
        //...Others properties
    ],

}

Create your own annotation

Note that getDocPage only work with the pre-defined annotations.
You will need to build your own html page base on the added annotations with getJson.

You can create your decorators for class and properties.
They will add the value(s) passed to them to the json generated by getJson under the key specified at their creation.
You create decorators with up to 3 parameters.

import { createPropertieAnnotation, createClassAnnotation } from "easy-typescript-documentation"

const my_class_annotation = createClassAnnotation<string>("myCustomKey")

const propertie_annotation = createPropertieAnnotation<number>("myCustomKey2")

const prop_annotation = createPropertieAnnotation<number,string>("number","string")

@Doc
@my_class_annotation("value")
class Exemple {

    @propertie_annotation(1)
    @prop_annotation(3,"value")
    id: number = 1
    
}

Here is the resulting json.

{
    myCustomKey: "value",
    properties : [
        {
            key: "id",
            type: "number",
            myCustomKey2: 1,
            number: 3,
            string: "value"
        }
    ]
}