README
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.
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"
}
]
}