diff options
Diffstat (limited to 'packages/website/ts/utils/typedoc_utils.ts')
-rw-r--r-- | packages/website/ts/utils/typedoc_utils.ts | 212 |
1 files changed, 133 insertions, 79 deletions
diff --git a/packages/website/ts/utils/typedoc_utils.ts b/packages/website/ts/utils/typedoc_utils.ts index 803cfa0cf..11ec8da58 100644 --- a/packages/website/ts/utils/typedoc_utils.ts +++ b/packages/website/ts/utils/typedoc_utils.ts @@ -1,34 +1,32 @@ import * as _ from 'lodash'; -import {DocsInfo} from 'ts/pages/documentation/docs_info'; +import { DocsInfo } from 'ts/pages/documentation/docs_info'; import { CustomType, CustomTypeChild, DocAgnosticFormat, DocSection, - DocsMenu, IndexSignature, KindString, - MenuSubsectionsBySection, Parameter, Property, SectionsMap, Type, TypeDocNode, TypeDocType, - TypeDocTypes, TypeParameter, TypescriptMethod, } from 'ts/types'; -import {constants} from 'ts/utils/constants'; -import {utils} from 'ts/utils/utils'; +import { utils } from 'ts/utils/utils'; export const typeDocUtils = { isType(entity: TypeDocNode): boolean { - return entity.kindString === KindString.Interface || - entity.kindString === KindString.Function || - entity.kindString === KindString['Type alias'] || - entity.kindString === KindString.Variable || - entity.kindString === KindString.Enumeration; + return ( + entity.kindString === KindString.Interface || + entity.kindString === KindString.Function || + entity.kindString === KindString.TypeAlias || + entity.kindString === KindString.Variable || + entity.kindString === KindString.Enumeration + ); }, isMethod(entity: TypeDocNode): boolean { return entity.kindString === KindString.Method; @@ -42,8 +40,10 @@ export const typeDocUtils = { isPrivateOrProtectedProperty(propertyName: string): boolean { return _.startsWith(propertyName, '_'); }, - getModuleDefinitionBySectionNameIfExists(versionDocObj: TypeDocNode, modulePaths: string[]): - TypeDocNode|undefined { + getModuleDefinitionBySectionNameIfExists( + versionDocObj: TypeDocNode, + modulePaths: string[], + ): TypeDocNode | undefined { const modules = versionDocObj.children; for (const mod of modules) { if (_.includes(modulePaths, mod.name)) { @@ -63,7 +63,8 @@ export const typeDocUtils = { return; // no-op } const packageDefinitionIfExists = typeDocUtils.getModuleDefinitionBySectionNameIfExists( - typeDocJson, modulePathsIfExists, + typeDocJson, + modulePathsIfExists, ); if (_.isUndefined(packageDefinitionIfExists)) { return; // no-op @@ -103,7 +104,11 @@ export const typeDocUtils = { case KindString.Constructor: isConstructor = true; const constructor = typeDocUtils._convertMethod( - entity, isConstructor, docsInfo.sections, sectionName, + entity, + isConstructor, + docsInfo.sections, + sectionName, + docsInfo.subPackageName, ); docSection.constructors.push(constructor); break; @@ -112,7 +117,11 @@ export const typeDocUtils = { if (entity.flags.isPublic) { isConstructor = false; const method = typeDocUtils._convertMethod( - entity, isConstructor, docsInfo.sections, sectionName, + entity, + isConstructor, + docsInfo.sections, + sectionName, + docsInfo.subPackageName, ); docSection.methods.push(method); } @@ -120,7 +129,12 @@ export const typeDocUtils = { case KindString.Property: if (!typeDocUtils.isPrivateOrProtectedProperty(entity.name)) { - const property = typeDocUtils._convertProperty(entity, docsInfo.sections, sectionName); + const property = typeDocUtils._convertProperty( + entity, + docsInfo.sections, + sectionName, + docsInfo.subPackageName, + ); docSection.properties.push(property); } break; @@ -129,9 +143,14 @@ export const typeDocUtils = { case KindString.Function: case KindString.Variable: case KindString.Enumeration: - case KindString['Type alias']: + case KindString.TypeAlias: if (docsInfo.isPublicType(entity.name)) { - const customType = typeDocUtils._convertCustomType(entity, docsInfo.sections, sectionName); + const customType = typeDocUtils._convertCustomType( + entity, + docsInfo.sections, + sectionName, + docsInfo.subPackageName, + ); docSection.types.push(customType); } break; @@ -142,34 +161,40 @@ export const typeDocUtils = { }); return docSection; }, - _convertCustomType(entity: TypeDocNode, sections: SectionsMap, sectionName: string): CustomType { - const typeIfExists = !_.isUndefined(entity.type) ? - typeDocUtils._convertType(entity.type, sections, sectionName) : - undefined; + _convertCustomType( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + subPackageName: string, + ): CustomType { + const typeIfExists = !_.isUndefined(entity.type) + ? typeDocUtils._convertType(entity.type, sections, sectionName, subPackageName) + : undefined; const isConstructor = false; - const methodIfExists = !_.isUndefined(entity.declaration) ? - typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName) : - undefined; - const indexSignatureIfExists = !_.isUndefined(entity.indexSignature) ? - typeDocUtils._convertIndexSignature(entity.indexSignature[0], sections, sectionName) : - undefined; - const commentIfExists = !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText) ? - entity.comment.shortText : - undefined; + const methodIfExists = !_.isUndefined(entity.declaration) + ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, subPackageName) + : undefined; + const indexSignatureIfExists = !_.isUndefined(entity.indexSignature) + ? typeDocUtils._convertIndexSignature(entity.indexSignature[0], sections, sectionName, subPackageName) + : undefined; + const commentIfExists = + !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText) + ? entity.comment.shortText + : undefined; - const childrenIfExist = !_.isUndefined(entity.children) ? - _.map(entity.children, (child: TypeDocNode) => { - const childTypeIfExists = !_.isUndefined(child.type) ? - typeDocUtils._convertType(child.type, sections, sectionName) : - undefined; - const c: CustomTypeChild = { - name: child.name, - type: childTypeIfExists, - defaultValue: child.defaultValue, - }; - return c; - }) : - undefined; + const childrenIfExist = !_.isUndefined(entity.children) + ? _.map(entity.children, (child: TypeDocNode) => { + const childTypeIfExists = !_.isUndefined(child.type) + ? typeDocUtils._convertType(child.type, sections, sectionName, subPackageName) + : undefined; + const c: CustomTypeChild = { + name: child.name, + type: childTypeIfExists, + defaultValue: child.defaultValue, + }; + return c; + }) + : undefined; const customType = { name: entity.name, @@ -183,21 +208,31 @@ export const typeDocUtils = { }; return customType; }, - _convertIndexSignature(entity: TypeDocNode, sections: SectionsMap, sectionName: string): IndexSignature { + _convertIndexSignature( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + subPackageName: string, + ): IndexSignature { const key = entity.parameters[0]; const indexSignature = { keyName: key.name, - keyType: typeDocUtils._convertType(key.type, sections, sectionName), + keyType: typeDocUtils._convertType(key.type, sections, sectionName, subPackageName), valueName: entity.type.name, }; return indexSignature; }, - _convertProperty(entity: TypeDocNode, sections: SectionsMap, sectionName: string): Property { + _convertProperty( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + subPackageName: string, + ): Property { const source = entity.sources[0]; const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; const property = { name: entity.name, - type: typeDocUtils._convertType(entity.type, sections, sectionName), + type: typeDocUtils._convertType(entity.type, sections, sectionName, subPackageName), source: { fileName: source.fileName, line: source.line, @@ -207,28 +242,39 @@ export const typeDocUtils = { return property; }, _convertMethod( - entity: TypeDocNode, isConstructor: boolean, sections: SectionsMap, sectionName: string, + entity: TypeDocNode, + isConstructor: boolean, + sections: SectionsMap, + sectionName: string, + subPackageName: string, ): TypescriptMethod { const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; - const topLevelInterface = isStatic ? 'ZeroEx.' : 'zeroEx.'; // HACK: we use the fact that the sectionName is the same as the property name at the top-level // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. - let callPath = (!_.isUndefined(sections.zeroEx) && sectionName !== sections.zeroEx) ? - `${topLevelInterface}${sectionName}.` : - topLevelInterface; - callPath = isConstructor || entity.name === '__type' ? '' : callPath; + let callPath; + if (isConstructor || entity.name === '__type') { + callPath = ''; + } else if (subPackageName === '0x.js') { + const topLevelInterface = isStatic ? 'ZeroEx.' : 'zeroEx.'; + callPath = + !_.isUndefined(sections.zeroEx) && sectionName !== sections.zeroEx + ? `${topLevelInterface}${sectionName}.` + : topLevelInterface; + } else { + callPath = `${sectionName}.`; + } const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName); + return typeDocUtils._convertParameter(param, sections, sectionName, subPackageName); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName); - const typeParameter = _.isUndefined(signature.typeParameter) ? - undefined : - typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName); + const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, subPackageName); + const typeParameter = _.isUndefined(signature.typeParameter) + ? undefined + : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, subPackageName); const method = { isConstructor, @@ -247,15 +293,25 @@ export const typeDocUtils = { }; return method; }, - _convertTypeParameter(entity: TypeDocNode, sections: SectionsMap, sectionName: string): TypeParameter { - const type = typeDocUtils._convertType(entity.type, sections, sectionName); + _convertTypeParameter( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + subPackageName: string, + ): TypeParameter { + const type = typeDocUtils._convertType(entity.type, sections, sectionName, subPackageName); const parameter = { name: entity.name, type, }; return parameter; }, - _convertParameter(entity: TypeDocNode, sections: SectionsMap, sectionName: string): Parameter { + _convertParameter( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + subPackageName: string, + ): Parameter { let comment = '<No comment>'; if (entity.comment && entity.comment.shortText) { comment = entity.comment.shortText; @@ -263,11 +319,9 @@ export const typeDocUtils = { comment = entity.comment.text; } - const isOptional = !_.isUndefined(entity.flags.isOptional) ? - entity.flags.isOptional : - false; + const isOptional = !_.isUndefined(entity.flags.isOptional) ? entity.flags.isOptional : false; - const type = typeDocUtils._convertType(entity.type, sections, sectionName); + const type = typeDocUtils._convertType(entity.type, sections, sectionName, subPackageName); const parameter = { name: entity.name, @@ -277,25 +331,25 @@ export const typeDocUtils = { }; return parameter; }, - _convertType(entity: TypeDocType, sections: SectionsMap, sectionName: string): Type { + _convertType(entity: TypeDocType, sections: SectionsMap, sectionName: string, subPackageName: string): Type { const typeArguments = _.map(entity.typeArguments, typeArgument => { - return typeDocUtils._convertType(typeArgument, sections, sectionName); + return typeDocUtils._convertType(typeArgument, sections, sectionName, subPackageName); }); const types = _.map(entity.types, t => { - return typeDocUtils._convertType(t, sections, sectionName); + return typeDocUtils._convertType(t, sections, sectionName, subPackageName); }); const isConstructor = false; - const methodIfExists = !_.isUndefined(entity.declaration) ? - typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName) : - undefined; + const methodIfExists = !_.isUndefined(entity.declaration) + ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, subPackageName) + : undefined; - const elementTypeIfExists = !_.isUndefined(entity.elementType) ? - { - name: entity.elementType.name, - typeDocType: entity.elementType.type, - } : - undefined; + const elementTypeIfExists = !_.isUndefined(entity.elementType) + ? { + name: entity.elementType.name, + typeDocType: entity.elementType.type, + } + : undefined; const type = { name: entity.name, |