feat: enum

Author: develar

.idea/dictionaries/develar.xml

@@ -1,7 +1,7 @@
 {
  "name": "ts-jsdoc",
  "description": "Transform TypeScript to JSDoc annotated JS code",
- "version": "1.0.7",
+ "version": "1.1.0",
  "license": "MIT",
  "bin": {
  "ts2jsdoc": "out/ts2jsdoc.js"

package.json

@@ -3,7 +3,7 @@ import * as path from "path"
 import { emptyDir, readdir, readFile, readJson, writeFile } from "fs-extra-p"
 import { JsDocRenderer } from "./JsDocRenderer"
 import { checkErrors, processTree } from "./util"
-import { Class, Member, MethodDescriptor, Property, SourceFileDescriptor, SourceFileModuleInfo, Variable } from "./psi"
+import { Class, Descriptor, Member, MethodDescriptor, Property, SourceFileDescriptor, SourceFileModuleInfo, Type, Variable } from "./psi"
 import BluebirdPromise from "bluebird-lst"
 
 export interface TsToJsdocOptions {
@@ -44,7 +44,7 @@ export async function generateAndWrite(basePath: string, config: ts.ParsedComman
  continue
  }
 
- moveMember(psi.functions, mainPsi.functions, name) || moveMember(psi.variables, mainPsi.variables, name)
+ moveMember(psi.functions, mainPsi.functions, name) || moveMember(psi.members, mainPsi.members, name)
  }
  }
 
@@ -53,12 +53,6 @@ export async function generateAndWrite(basePath: string, config: ts.ParsedComman
  const existingClassExampleDirs = exampleDir == null ? null : new Set((await readdir(exampleDir)).filter(it => it[0] != "." && !it.includes(".")))
 
  for (const [moduleId, psi] of moduleNameToResult.entries()) {
- let result = ""
- const externalToModuleName = new Map<string, string>()
- for (const d of copyAndSort(psi.variables)) {
- result += generator.renderer.renderVariable(d)
- }
- 
  const modulePathMapper: ModulePathMapper = oldPath => {
  if (!oldPath.startsWith("module:")) {
  return oldPath
@@ -81,6 +75,17 @@ export async function generateAndWrite(basePath: string, config: ts.ParsedComman
  return oldPath
  }
 
+ let result = ""
+ const externalToModuleName = new Map<string, string>()
+ for (const d of copyAndSort(psi.members)) {
+ if ((<any>d).kind == null) {
+ result += generator.renderer.renderVariable(<Variable>d, modulePathMapper)
+ }
+ else {
+ result += generator.renderer.renderMember(<Descriptor>d)
+ }
+ }
+ 
  for (const d of copyAndSort(psi.classes)) {
  let examples: Array<Example> = []
  if (existingClassExampleDirs != null && existingClassExampleDirs.has(d.name)) {
@@ -215,7 +220,7 @@ export class JsDocGenerator {
 
  const classes: Array<Class> = []
  const functions: Array<MethodDescriptor> = []
- const variables: Array<Variable> = []
+ const members: Array<Variable | Descriptor> = []
 
  processTree(sourceFile, (node) => {
  if (node.kind === ts.SyntaxKind.InterfaceDeclaration || node.kind === ts.SyntaxKind.ClassDeclaration) {
@@ -240,20 +245,26 @@ export class JsDocGenerator {
  else if (node.kind === ts.SyntaxKind.VariableStatement) {
  const descriptor = this.describeVariable(<ts.VariableStatement>node)
  if (descriptor != null) {
- variables.push(descriptor)
+ members.push(descriptor)
+ }
+ }
+ else if (node.kind === ts.SyntaxKind.EnumDeclaration) {
+ const descriptor = this.describeEnum(<ts.EnumDeclaration>node)
+ if (descriptor != null) {
+ members.push(descriptor)
  }
  }
  return true
  })
 
  const existingPsi = this.moduleNameToResult.get(moduleId.id)
  if (existingPsi == null) {
- this.moduleNameToResult.set(moduleId.id, {classes, functions, variables})
+ this.moduleNameToResult.set(moduleId.id, {classes, functions, members})
  }
  else {
  existingPsi.classes.push(...classes)
  existingPsi.functions.push(...functions)
- existingPsi.variables.push(...variables)
+ existingPsi.members.push(...members)
  }
  }
 
@@ -292,7 +303,7 @@ export class JsDocGenerator {
  this.mainMappings.set(this.sourceFileToModuleId(sourceFile).id, names)
  }
 
- getTypeNamePathByNode(node: ts.Node): Array<string> | null {
+ getTypeNamePathByNode(node: ts.Node): Array<string | Type> | null {
  if (node.kind === ts.SyntaxKind.UnionType) {
  return this.typesToList((<ts.UnionType>(<any>node)).types, node)
  }
@@ -318,33 +329,46 @@ export class JsDocGenerator {
  const text = (<ts.LiteralLikeNode>(<any>(<ts.LiteralTypeNode>node).literal)).text
  return [`"${text}"`]
  }
+ else if (node.kind === ts.SyntaxKind.TypeLiteral) {
+ // todo
+ return ['Object.<string, any>']
+ }
 
  const type = this.program.getTypeChecker().getTypeAtLocation(node)
- if (type == null) {
- return null
+ return type == null ? null : this.getTypeNames(type, node)
+ }
+
+ private typesToList(types: Array<ts.Type>, node: ts.Node) {
+ const typeNames: Array<string | Type> = []
+ for (const type of types) {
+ const name = (<any>type).kind == null ? [this.getTypeNamePath(<any>type)] : this.getTypeNamePathByNode(<any>type)
+ if (name == null) {
+ throw new Error("cannot get name for " + node.getText(node.getSourceFile()))
+ }
+ typeNames.push(...name)
  }
+ return typeNames
+ }
 
+ getTypeNames(type: ts.Type, node: ts.Node): Array<string | Type> | null {
  if (type.flags & ts.TypeFlags.UnionOrIntersection && !(type.flags & ts.TypeFlags.Enum)) {
  return this.typesToList((<ts.UnionOrIntersectionType>type).types, node)
  }
- 
+
  let result = this.getTypeNamePath(type)
  if (result == null) {
  throw new Error("Cannot infer getTypeNamePath")
  }
- return [result]
- }
 
- private typesToList(types: Array<ts.Type>, node: ts.Node) {
- const typeNames: Array<string> = []
- for (const type of types) {
- const name = (<any>type).kind == null ? [this.getTypeNamePath(<any>type)] : this.getTypeNamePathByNode(<any>type)
- if (name == null) {
- throw new Error("cannot get name for " + node.getText(node.getSourceFile()))
+ const typeArguments = (<ts.TypeReference>type).typeArguments
+ if (typeArguments != null) {
+ const subTypes = []
+ for (const type of typeArguments) {
+ subTypes.push(...this.getTypeNames(type, node))
  }
- typeNames.push(...name)
+ return [{name: result, subTypes: subTypes}]
  }
- return typeNames
+ return [result]
  }
 
  getTypeNamePath(type: ts.Type): string | null {
@@ -407,6 +431,47 @@ export class JsDocGenerator {
  console.warn(`Cannot find parent for ${symbol}`)
  return null
  }
+ 
+ private describeEnum(node: ts.EnumDeclaration): Descriptor {
+ const flags = ts.getCombinedModifierFlags(node)
+ if (!(flags & ts.ModifierFlags.Export)) {
+ return null
+ }
+ 
+ const type = {
+ names: ["number"]
+ }
+ 
+ const name = (<ts.Identifier>node.name).text
+ const moduleId = this.computeTypePath()
+ const id = `${moduleId}.${name}`
+ 
+ const properties: Array<Descriptor> = []
+ for (const member of node.members) {
+ const name = (<ts.Identifier>member.name).text
+ properties.push({
+ name: name,
+ kind: "member",
+ scope: "static",
+ memberof: id,
+ type: type,
+ })
+ }
+
+ // we don't set readonly because it is clear that enum is not mutable
+ // e.g. jsdoc2md wil add useless "Read only: true"
+ return {
+ node: node,
+ id: id,
+ name: name,
+ longname: id,
+ kind: "enum",
+ scope: "static",
+ memberof: moduleId,
+ type: type,
+ properties: properties,
+ }
+ }
 
  private describeVariable(node: ts.VariableStatement): Variable {
  const flags = ts.getCombinedModifierFlags(node)
@@ -456,7 +521,7 @@ export class JsDocGenerator {
  const className = (<ts.Identifier>nodeDeclaration.name).text
 
  const clazz = <ts.ClassDeclaration>node
- let parents: Array<string> = []
+ let parents: Array<string | Type> = []
  if (clazz.heritageClauses != null) {
  for (const heritageClause of clazz.heritageClauses) {
  if (heritageClause.types != null) {

src/JsDocGenerator.ts

@@ -2,7 +2,7 @@ import * as ts from "typescript"
 import * as path from "path"
 import { Example, JsDocGenerator, ModulePathMapper } from "./JsDocGenerator"
 import { parse as parseJsDoc, Tag } from "doctrine"
-import { Class, MethodDescriptor, Property, Variable } from "./psi"
+import { Class, Descriptor, MethodDescriptor, Property, Type, Variable } from "./psi"
 
 export class JsDocRenderer {
  indent: string = ""
@@ -54,7 +54,8 @@ export class JsDocRenderer {
  }
 
  for (const parent of descriptor.parents) {
- tags.push(`@extends ${modulePathMapper(parent)}`)
+ // ignore <> type params because JsDoc expects namepath, but not type expression 
+ tags.push(`@extends ${renderType(parent, modulePathMapper, true)}`)
  }
 
  JsDocRenderer.renderProperties(descriptor.properties, tags, modulePathMapper)
@@ -96,7 +97,7 @@ export class JsDocRenderer {
  returns = tag
  }
  else {
- tags.push(`@${tag.title} ${tag.description}`)
+ tags.push(printTag(tag))
  }
  }
  }
@@ -112,17 +113,17 @@ export class JsDocRenderer {
 
  const tag = paramNameToInfo.get(name)
  text += ` ${name}`
- if (tag != null) {
+ if (tag != null && tag.description != null) {
  text += ` ${tag.description}`
  }
  tags.push(text)
  }
 
  const signature = this.generator.program.getTypeChecker().getSignatureFromDeclaration(method.node)
- const returnType = this.generator.getTypeNamePath(signature.getReturnType())
+ const returnTypes = this.generator.getTypeNames(signature.getReturnType(), method.node)
  // http://stackoverflow.com/questions/4759175/how-to-return-void-in-jsdoc
- if (returnType !== "void") {
- let text = `@returns ${renderTypes([returnType])}`
+ if (!returnTypes.includes("void")) {
+ let text = `@returns ${renderTypes(returnTypes, modulePathMapper)}`
  if (returns != null) {
  text += ` ${returns.description}`
  }
@@ -152,10 +153,10 @@ export class JsDocRenderer {
  return null
  }
 
- renderVariable(descriptor: Variable): string {
+ renderVariable(descriptor: Variable, modulePathMapper: ModulePathMapper): string {
  this.indent = ""
 
- const tags = [`@type ${renderTypes(descriptor.types)}`]
+ const tags = [`@type ${renderTypes(descriptor.types, modulePathMapper)}`]
 
  if (descriptor.isConst) {
  tags.push("@constant")
@@ -166,6 +167,23 @@ export class JsDocRenderer {
  result += `export var ${descriptor.name}\n`
  return result
  }
+ 
+ renderMember(descriptor: Descriptor) {
+ const tags = [
+ "@enum {number}"
+ ]
+ 
+ if (descriptor.readonly) {
+ tags.push("@readonly") 
+ }
+ for (const property of descriptor.properties) {
+ tags.push(`@property ${property.name}`) 
+ }
+ 
+ let result = this.formatComment(descriptor.node!, tags)
+ result += `export var ${descriptor.name}\n`
+ return result
+ }
 
  // form http://stackoverflow.com/questions/10490713/how-to-document-the-properties-of-the-object-in-the-jsdoc-3-tag-this
  // doesn't produce properties table, so, we use property tags
@@ -246,26 +264,44 @@ function parseExistingJsDoc(node: ts.Node, tags: Array<string>): string | null {
  const parsed = existingJsDoc == null ? null : parseJsDoc(existingJsDoc, {unwrap: true})
  if (parsed != null) {
  for (const tag of parsed.tags) {
- let text = `@${tag.title}`
- 
- const caption = (<any>tag).caption
- if (caption != null) {
- text += ` <caption>${caption}</caption>`
- }
- 
- if (tag.description != null) {
- text += ` ${tag.description}`
- }
- tags.push(text)
+ tags.push(printTag(tag))
  }
  }
 
  return parsed == null ? null : parsed.description
 }
 
-function renderTypes(names: Array<string>, modulePathMapper?: ModulePathMapper) {
- if (modulePathMapper != null) {
- names = names.map(it => modulePathMapper(it) || it)
+function printTag(tag: Tag) {
+ let text = `@${tag.title}`
+
+ const caption = (<any>tag).caption
+ if (caption != null) {
+ text += ` <caption>${caption}</caption>`
+ }
+
+ if (tag.description != null) {
+ text += ` ${tag.description}`
+ }
+ return text
+}
+
+// (oldPath: string) => oldPath
+
+function renderTypes(names: Array<string | Type>, modulePathMapper: ModulePathMapper): string {
+ return `{${_renderTypes(names, modulePathMapper)}}`
+}
+
+function _renderTypes(names: Array<string | Type>, modulePathMapper: ModulePathMapper): string {
+ return names.map(it => renderType(it, modulePathMapper)).join(" | ")
+}
+
+function renderType(name: string | Type, modulePathMapper: ModulePathMapper, ignoreSubtypes = false): string {
+ if (typeof name === "string") {
+ return modulePathMapper(name)
+ }
+ const type = <Type>name
+ if (ignoreSubtypes) {
+ return modulePathMapper(type.name)
  }
- return `{${names.join(" | ")}}`
+ return modulePathMapper(type.name) + "<" + _renderTypes(type.subTypes, modulePathMapper) + ">"
 }