diff options
Diffstat (limited to 'packages/react-docs')
-rw-r--r-- | packages/react-docs/README.md | 6 | ||||
-rw-r--r-- | packages/react-docs/package.json | 10 | ||||
-rw-r--r-- | packages/react-docs/src/components/documentation.tsx | 85 | ||||
-rw-r--r-- | packages/react-docs/src/components/event_definition.tsx | 7 | ||||
-rw-r--r-- | packages/react-docs/src/components/interface.tsx | 33 | ||||
-rw-r--r-- | packages/react-docs/src/components/property_block.tsx | 78 | ||||
-rw-r--r-- | packages/react-docs/src/components/signature.tsx | 25 | ||||
-rw-r--r-- | packages/react-docs/src/components/signature_block.tsx | 5 | ||||
-rw-r--r-- | packages/react-docs/src/components/type.tsx | 117 | ||||
-rw-r--r-- | packages/react-docs/src/components/type_definition.tsx | 22 | ||||
-rw-r--r-- | packages/react-docs/src/docs_info.ts | 79 | ||||
-rw-r--r-- | packages/react-docs/src/index.ts | 10 | ||||
-rw-r--r-- | packages/react-docs/src/monorepo_scripts/postpublish.ts | 8 | ||||
-rw-r--r-- | packages/react-docs/src/types.ts | 52 | ||||
-rw-r--r-- | packages/react-docs/src/utils/constants.ts | 1 | ||||
-rw-r--r-- | packages/react-docs/src/utils/typedoc_utils.ts | 435 |
16 files changed, 603 insertions, 370 deletions
diff --git a/packages/react-docs/README.md b/packages/react-docs/README.md index c0efc4a0b..5d56207de 100644 --- a/packages/react-docs/README.md +++ b/packages/react-docs/README.md @@ -1,6 +1,8 @@ ## @0xproject/react-docs -A full-page React component for rendering beautiful documentation for Solidity and Typescript code generated with [TypeDoc](http://typedoc.org/) or [Doxity](https://github.com/0xproject/doxity). See a [live example](http://react-docs-example.s3-website-us-east-1.amazonaws.com/). +#### WARNING: Alpha software. Expect things to break when trying to use. + +A full-page React component for rendering beautiful documentation for Solidity and Typescript code generated with [TypeDoc](http://typedoc.org/) or [Doxity](https://github.com/0xproject/doxity). <div style="text-align: center;"> <img src="https://s3.eu-west-2.amazonaws.com/0x-wiki-images/screenshot.png" style="padding-bottom: 20px; padding-top: 20px;" width="80%" /> @@ -27,8 +29,6 @@ yarn add @0xproject/react-docs ## Usage -View the [live example](http://react-docs-example.s3-website-us-east-1.amazonaws.com/) that renders the [@0xproject/web3-wrapper](https://github.com/0xProject/0x-monorepo/tree/development/packages/web3-wrapper) Typescript package. It's source code is in the [react-docs-example](https://github.com/0xProject/0x-monorepo/tree/development/packages/react-docs-example) 0x monorepo subpackage. - This package exposes both a single `Documentation` react component that will render a docs page, as well as all of it's sub-components in case someone wants to build their own layout. Currently this package still has some external dependencies outside of the `Documentation` component, so please start your project off by copying the [react-docs-example](https://github.com/0xProject/0x-monorepo/tree/development/packages/react-docs-example) directory and modifying it there. If you need changes in the [react-docs](https://github.com/0xProject/0x-monorepo/tree/development/packages/react-docs) package, fork the 0x monorepo, make the required changes and submit a PR. Until we merge it, you can have your project depend on your own custom fork. diff --git a/packages/react-docs/package.json b/packages/react-docs/package.json index f09bb64a0..aeface8d7 100644 --- a/packages/react-docs/package.json +++ b/packages/react-docs/package.json @@ -9,10 +9,9 @@ "types": "lib/index.d.ts", "scripts": { "lint": "tslint --project .", - "build": "tsc && copyfiles -u 2 './lib/monorepo_scripts/**/*' ./scripts", + "build": "tsc", "watch_without_deps": "tsc -w", - "clean": "shx rm -rf lib scripts", - "manual:postpublish": "yarn build; node ./scripts/postpublish.js" + "clean": "shx rm -rf lib" }, "author": "Fabio Berger", "license": "Apache-2.0", @@ -26,7 +25,6 @@ }, "devDependencies": { "@0xproject/dev-utils": "^1.0.4", - "@0xproject/monorepo-scripts": "^1.0.5", "@0xproject/tslint-config": "^1.0.5", "@types/compare-versions": "^3.0.0", "copyfiles": "^2.0.0", @@ -43,7 +41,7 @@ "@types/node": "^8.0.53", "@types/react": "*", "@types/react-dom": "*", - "@types/react-scroll": "0.0.31", + "@types/react-scroll": "1.5.3", "basscss": "^8.0.3", "compare-versions": "^3.0.1", "lodash": "^4.17.5", @@ -51,7 +49,7 @@ "react": "15.6.1", "react-dom": "15.6.1", "react-markdown": "^3.2.2", - "react-scroll": "^1.5.2", + "react-scroll": "0xproject/react-scroll#similar-to-pr-330", "react-tooltip": "^3.2.7", "semver": "5.5.0" }, diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index ff33220d2..9d9b5141a 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -19,6 +19,7 @@ import { AddressByContractName, DocAgnosticFormat, Event, + ExternalExportToLink, Property, SolidityMethod, SupportedDocJson, @@ -31,9 +32,8 @@ import { constants } from '../utils/constants'; import { Badge } from './badge'; import { Comment } from './comment'; import { EventDefinition } from './event_definition'; +import { PropertyBlock } from './property_block'; import { SignatureBlock } from './signature_block'; -import { SourceLink } from './source_link'; -import { Type } from './type'; import { TypeDefinition } from './type_definition'; const networkNameToColor: { [network: string]: string } = { @@ -129,7 +129,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta selectedVersion={this.props.selectedVersion} versions={this.props.availableVersions} sidebarHeader={this.props.sidebarHeader} - topLevelMenu={this.props.docsInfo.getMenu(this.props.selectedVersion)} + topLevelMenu={this.props.docsInfo.menu} menuSubsectionsBySection={menuSubsectionsBySection} onVersionSelected={this.props.onVersionSelected} /> @@ -172,7 +172,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta ); } private _renderDocumentation(): React.ReactNode { - const subMenus = _.values(this.props.docsInfo.getMenu()); + const subMenus = _.values(this.props.docsInfo.menu); const orderedSectionNames = _.flatten(subMenus); const typeDefinitionByName = this.props.docsInfo.getTypeDefinitionsByName(this.props.docAgnosticFormat); @@ -210,6 +210,14 @@ export class Documentation extends React.Component<DocumentationProps, Documenta return null; } + const isExportedFunctionSection = + docSection.functions.length === 1 && + _.isEmpty(docSection.types) && + _.isEmpty(docSection.methods) && + _.isEmpty(docSection.constructors) && + _.isEmpty(docSection.properties) && + _.isEmpty(docSection.events); + const sortedTypes = _.sortBy(docSection.types, 'name'); const typeDefs = _.map(sortedTypes, customType => { return ( @@ -218,12 +226,17 @@ export class Documentation extends React.Component<DocumentationProps, Documenta key={`type-${customType.name}`} customType={customType} docsInfo={this.props.docsInfo} + typeDefinitionByName={typeDefinitionByName} + isInPopover={false} /> ); }); const sortedProperties = _.sortBy(docSection.properties, 'name'); - const propertyDefs = _.map(sortedProperties, this._renderProperty.bind(this, sectionName)); + const propertyDefs = _.map( + sortedProperties, + this._renderProperty.bind(this, sectionName, typeDefinitionByName), + ); const sortedMethods = _.sortBy(docSection.methods, 'name'); const methodDefs = _.map(sortedMethods, method => { @@ -258,13 +271,12 @@ export class Documentation extends React.Component<DocumentationProps, Documenta {this._renderNetworkBadgesIfExists(sectionName)} </div> {docSection.comment && <Comment comment={docSection.comment} />} - {!_.isEmpty(docSection.constructors) && - this.props.docsInfo.isVisibleConstructor(sectionName) && ( - <div> - <h2 style={headerStyle}>Constructor</h2> - {this._renderConstructors(docSection.constructors, sectionName, typeDefinitionByName)} - </div> - )} + {!_.isEmpty(docSection.constructors) && ( + <div> + <h2 style={headerStyle}>Constructor</h2> + {this._renderConstructors(docSection.constructors, sectionName, typeDefinitionByName)} + </div> + )} {!_.isEmpty(docSection.properties) && ( <div> <h2 style={headerStyle}>Properties</h2> @@ -279,7 +291,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta )} {!_.isEmpty(docSection.functions) && ( <div> - <h2 style={headerStyle}>Functions</h2> + {!isExportedFunctionSection && <h2 style={headerStyle}>Functions</h2>} <div>{functionDefs}</div> </div> )} @@ -290,6 +302,8 @@ export class Documentation extends React.Component<DocumentationProps, Documenta <div>{eventDefs}</div> </div> )} + {!_.isUndefined(docSection.externalExportToLink) && + this._renderExternalExports(docSection.externalExportToLink)} {!_.isUndefined(typeDefs) && typeDefs.length > 0 && ( <div> @@ -299,6 +313,22 @@ export class Documentation extends React.Component<DocumentationProps, Documenta </div> ); } + private _renderExternalExports(externalExportToLink: ExternalExportToLink): React.ReactNode { + const externalExports = _.map(externalExportToLink, (link: string, exportName: string) => { + return ( + <div className="pt2" key={`external-export-${exportName}`}> + <code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}> + {`import { `} + <a href={link} target="_blank" style={{ color: colors.lightBlueA700, textDecoration: 'none' }}> + {exportName} + </a> + {` } from '${this.props.docsInfo.packageName}'`} + </code> + </div> + ); + }); + return <div>{externalExports}</div>; + } private _renderNetworkBadgesIfExists(sectionName: string): React.ReactNode { if (this.props.docsInfo.type !== SupportedDocJson.Doxity) { return null; @@ -343,22 +373,21 @@ export class Documentation extends React.Component<DocumentationProps, Documenta }); return <div>{constructorDefs}</div>; } - private _renderProperty(sectionName: string, property: Property): React.ReactNode { + private _renderProperty( + sectionName: string, + typeDefinitionByName: TypeDefinitionByName, + property: Property, + ): React.ReactNode { return ( - <div key={`property-${property.name}-${property.type.name}`} className="pb3"> - <code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}> - {property.name}:{' '} - <Type type={property.type} sectionName={sectionName} docsInfo={this.props.docsInfo} /> - </code> - {property.source && ( - <SourceLink - version={this.props.selectedVersion} - source={property.source} - sourceUrl={this.props.sourceUrl} - /> - )} - {property.comment && <Comment comment={property.comment} className="py2" />} - </div> + <PropertyBlock + key={`property-${property.name}-${property.type.name}`} + property={property} + sectionName={sectionName} + docsInfo={this.props.docsInfo} + sourceUrl={this.props.sourceUrl} + selectedVersion={this.props.selectedVersion} + typeDefinitionByName={typeDefinitionByName} + /> ); } private _renderSignatureBlocks( diff --git a/packages/react-docs/src/components/event_definition.tsx b/packages/react-docs/src/components/event_definition.tsx index b4dc729a9..6cb80c6b0 100644 --- a/packages/react-docs/src/components/event_definition.tsx +++ b/packages/react-docs/src/components/event_definition.tsx @@ -53,7 +53,12 @@ export class EventDefinition extends React.Component<EventDefinitionProps, Event const indexed = <span style={{ color: colors.green }}> indexed</span>; const eventArgs = _.map(this.props.event.eventArgs, (eventArg: EventArg) => { const type = ( - <Type type={eventArg.type} sectionName={this.props.sectionName} docsInfo={this.props.docsInfo} /> + <Type + type={eventArg.type} + sectionName={this.props.sectionName} + docsInfo={this.props.docsInfo} + isInPopover={false} + /> ); return ( <span key={`eventArg-${eventArg.name}`}> diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index a881c7fec..93b10e96d 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -2,26 +2,28 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, TypeDocTypes } from '../types'; +import { CustomType, TypeDefinitionByName } from '../types'; import { Signature } from './signature'; import { Type } from './type'; +const defaultProps = {}; + export interface InterfaceProps { type: CustomType; sectionName: string; docsInfo: DocsInfo; + typeDefinitionByName: TypeDefinitionByName; + isInPopover: boolean; } -export const Interface = (props: InterfaceProps) => { +export const Interface: React.SFC<InterfaceProps> = (props: InterfaceProps): any => { const type = props.type; const properties = _.map(type.children, property => { return ( <span key={`property-${property.name}-${property.type}-${type.name}`}> {property.name}:{' '} - {property.type && property.type.typeDocType !== TypeDocTypes.Reflection ? ( - <Type type={property.type} sectionName={props.sectionName} docsInfo={props.docsInfo} /> - ) : ( + {property.type && !_.isUndefined(property.type.method) ? ( <Signature name={property.type.method.name} returnType={property.type.method.returnType} @@ -31,6 +33,16 @@ export const Interface = (props: InterfaceProps) => { shouldHideMethodName={true} shouldUseArrowSyntax={true} docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} + /> + ) : ( + <Type + type={property.type} + sectionName={props.sectionName} + docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> )}, </span> @@ -41,7 +53,14 @@ export const Interface = (props: InterfaceProps) => { const is = type.indexSignature; const param = ( <span key={`indexSigParams-${is.keyName}-${is.keyType}-${type.name}`}> - {is.keyName}: <Type type={is.keyType} sectionName={props.sectionName} docsInfo={props.docsInfo} /> + {is.keyName}:{' '} + <Type + type={is.keyType} + sectionName={props.sectionName} + docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} + /> </span> ); properties.push( @@ -64,3 +83,5 @@ export const Interface = (props: InterfaceProps) => { </span> ); }; + +Interface.defaultProps = defaultProps; diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx new file mode 100644 index 000000000..f181e21d2 --- /dev/null +++ b/packages/react-docs/src/components/property_block.tsx @@ -0,0 +1,78 @@ +import { AnchorTitle, HeaderSizes } from '@0xproject/react-shared'; +import * as React from 'react'; + +import { DocsInfo } from '../docs_info'; +import { Property, TypeDefinitionByName } from '../types'; +import { constants } from '../utils/constants'; + +import { Comment } from './comment'; +import { SourceLink } from './source_link'; +import { Type } from './type'; + +export interface PropertyBlockProps { + property: Property; + sectionName: string; + docsInfo: DocsInfo; + sourceUrl: string; + selectedVersion: string; + typeDefinitionByName: TypeDefinitionByName; +} + +export interface PropertyBlockState { + shouldShowAnchor: boolean; +} + +export class PropertyBlock extends React.Component<PropertyBlockProps, PropertyBlockState> { + constructor(props: PropertyBlockProps) { + super(props); + this.state = { + shouldShowAnchor: false, + }; + } + public render(): React.ReactNode { + const property = this.props.property; + const sectionName = this.props.sectionName; + return ( + <div + id={`${this.props.sectionName}-${property.name}`} + className="pb4 pt2" + key={`property-${property.name}-${property.type.name}`} + onMouseOver={this._setAnchorVisibility.bind(this, true)} + onMouseOut={this._setAnchorVisibility.bind(this, false)} + > + <div className="pb2" style={{ lineHeight: 1.3 }}> + <AnchorTitle + headerSize={HeaderSizes.H3} + title={property.name} + id={`${sectionName}-${property.name}`} + shouldShowAnchor={this.state.shouldShowAnchor} + /> + </div> + <code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}> + {(property as any).callPath} + {property.name}:{' '} + <Type + type={property.type} + sectionName={sectionName} + docsInfo={this.props.docsInfo} + typeDefinitionByName={this.props.typeDefinitionByName} + isInPopover={false} + /> + </code> + {property.source && ( + <SourceLink + version={this.props.selectedVersion} + source={property.source} + sourceUrl={this.props.sourceUrl} + /> + )} + {property.comment && <Comment comment={property.comment} className="py2" />} + </div> + ); + } + private _setAnchorVisibility(shouldShowAnchor: boolean): void { + this.setState({ + shouldShowAnchor, + }); + } +} diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index 77e9cc909..bf9c8be24 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -3,7 +3,6 @@ import * as React from 'react'; import { DocsInfo } from '../docs_info'; import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '../types'; -import { constants } from '../utils/constants'; import { Type } from './type'; @@ -18,6 +17,7 @@ export interface SignatureProps { typeParameter?: TypeParameter; callPath?: string; docsInfo: DocsInfo; + isInPopover: boolean; } const defaultProps = { @@ -27,8 +27,14 @@ const defaultProps = { }; export const Signature: React.SFC<SignatureProps> = (props: SignatureProps) => { - const sectionName = constants.TYPES_SECTION_NAME; - const parameters = renderParameters(props.parameters, props.docsInfo, sectionName, props.typeDefinitionByName); + const sectionName = props.sectionName; + const parameters = renderParameters( + props.parameters, + props.docsInfo, + sectionName, + props.isInPopover, + props.typeDefinitionByName, + ); const paramStringArray: any[] = []; // HACK: For now we don't put params on newlines if there are less then 2 of them. // Ideally we would check the character length of the resulting method signature and @@ -58,7 +64,13 @@ export const Signature: React.SFC<SignatureProps> = (props: SignatureProps) => { const methodName = props.shouldHideMethodName ? '' : props.name; const typeParameterIfExists = _.isUndefined(props.typeParameter) ? undefined - : renderTypeParameter(props.typeParameter, props.docsInfo, sectionName, props.typeDefinitionByName); + : renderTypeParameter( + props.typeParameter, + props.docsInfo, + sectionName, + props.isInPopover, + props.typeDefinitionByName, + ); return ( <span style={{ fontSize: 15 }}> {props.callPath} @@ -73,6 +85,7 @@ export const Signature: React.SFC<SignatureProps> = (props: SignatureProps) => { sectionName={sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> </span> )} @@ -86,6 +99,7 @@ function renderParameters( parameters: Parameter[], docsInfo: DocsInfo, sectionName: string, + isInPopover: boolean, typeDefinitionByName?: TypeDefinitionByName, ): React.ReactNode[] { const params = _.map(parameters, (p: Parameter) => { @@ -97,6 +111,7 @@ function renderParameters( sectionName={sectionName} typeDefinitionByName={typeDefinitionByName} docsInfo={docsInfo} + isInPopover={isInPopover} /> ); return ( @@ -114,6 +129,7 @@ function renderTypeParameter( typeParameter: TypeParameter, docsInfo: DocsInfo, sectionName: string, + isInPopover: boolean, typeDefinitionByName?: TypeDefinitionByName, ): React.ReactNode { const typeParam = ( @@ -124,6 +140,7 @@ function renderTypeParameter( sectionName={sectionName} typeDefinitionByName={typeDefinitionByName} docsInfo={docsInfo} + isInPopover={isInPopover} /> {`>`} </span> diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 9e5198e16..05145dc23 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -5,7 +5,6 @@ import * as React from 'react'; import { DocsInfo } from '../docs_info'; import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptFunction, TypescriptMethod } from '../types'; import { constants } from '../utils/constants'; -import { typeDocUtils } from '../utils/typedoc_utils'; import { Comment } from './comment'; import { Signature } from './signature'; @@ -44,9 +43,6 @@ export class SignatureBlock extends React.Component<SignatureBlockProps, Signatu } public render(): React.ReactNode { const method = this.props.method; - if (typeDocUtils.isPrivateOrProtectedProperty(method.name)) { - return null; - } return ( <div @@ -81,6 +77,7 @@ export class SignatureBlock extends React.Component<SignatureBlockProps, Signatu sectionName={this.props.sectionName} typeDefinitionByName={this.props.typeDefinitionByName} docsInfo={this.props.docsInfo} + isInPopover={false} /> </code> {(method as TypescriptMethod).source && ( diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index e453349ef..145c797a3 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -7,20 +7,26 @@ import * as ReactTooltip from 'react-tooltip'; import { DocsInfo } from '../docs_info'; import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types'; +import { constants } from '../utils/constants'; import { Signature } from './signature'; import { TypeDefinition } from './type_definition'; +const basicJsTypes = ['string', 'number', 'undefined', 'null', 'boolean']; + +const defaultProps = {}; + export interface TypeProps { type: TypeDef; docsInfo: DocsInfo; sectionName: string; typeDefinitionByName?: TypeDefinitionByName; + isInPopover: boolean; } // The return type needs to be `any` here so that we can recursively define <Type /> components within // <Type /> components (e.g when rendering the union type). -export function Type(props: TypeProps): any { +export const Type: React.SFC<TypeProps> = (props: TypeProps): any => { const type = props.type; const isReference = type.typeDocType === TypeDocTypes.Reference; const isArray = type.typeDocType === TypeDocTypes.Array; @@ -43,10 +49,11 @@ export function Type(props: TypeProps): any { <span> <Type key={key} - type={arg.elementType} + type={arg} sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} />[] </span> ); @@ -58,6 +65,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); return subType; @@ -72,6 +80,9 @@ export function Type(props: TypeProps): any { case TypeDocTypes.Array: typeName = type.elementType.name; + if (_.includes(basicJsTypes, typeName)) { + typeNameColor = colors.orange; + } break; case TypeDocTypes.Union: @@ -83,6 +94,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); }); @@ -92,19 +104,45 @@ export function Type(props: TypeProps): any { break; case TypeDocTypes.Reflection: - typeName = ( - <Signature - name={type.method.name} - returnType={type.method.returnType} - parameters={type.method.parameters} - typeParameter={type.method.typeParameter} - sectionName={props.sectionName} - shouldHideMethodName={true} - shouldUseArrowSyntax={true} - docsInfo={props.docsInfo} - typeDefinitionByName={props.typeDefinitionByName} - /> - ); + if (!_.isUndefined(type.method)) { + typeName = ( + <Signature + name={type.method.name} + returnType={type.method.returnType} + parameters={type.method.parameters} + typeParameter={type.method.typeParameter} + sectionName={props.sectionName} + shouldHideMethodName={true} + shouldUseArrowSyntax={true} + docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} + /> + ); + } else if (!_.isUndefined(type.indexSignature)) { + const is = type.indexSignature; + const param = ( + <span key={`indexSigParams-${is.keyName}-${is.keyType}-${type.name}`}> + {is.keyName}:{' '} + <Type + type={is.keyType} + sectionName={props.sectionName} + docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} + /> + </span> + ); + typeName = ( + <span key={`indexSignature-${type.name}-${is.keyType.name}`}> + {'{'}[{param}]: {is.valueName} + {'}'} + </span> + ); + } else { + throw new Error(`Unrecognized Reflection type that isn't a Method nor an Index Signature`); + } + break; case TypeDocTypes.TypeParameter: @@ -120,6 +158,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); }); @@ -140,20 +179,8 @@ export function Type(props: TypeProps): any { return [prev, ', ', curr]; }); - let typeNameUrlIfExists; - let typePrefixIfExists; - let sectionNameIfExists; - if (!_.isUndefined(props.docsInfo.typeConfigs)) { - typeNameUrlIfExists = !_.isUndefined(props.docsInfo.typeConfigs.typeNameToExternalLink) - ? props.docsInfo.typeConfigs.typeNameToExternalLink[typeName as string] - : undefined; - typePrefixIfExists = !_.isUndefined(props.docsInfo.typeConfigs.typeNameToPrefix) - ? props.docsInfo.typeConfigs.typeNameToPrefix[typeName as string] - : undefined; - sectionNameIfExists = !_.isUndefined(props.docsInfo.typeConfigs.typeNameToDocSection) - ? props.docsInfo.typeConfigs.typeNameToDocSection[typeName as string] - : undefined; - } + const isExportedClassReference = !!props.type.isExportedClassReference; + const typeNameUrlIfExists = !_.isUndefined(props.type.externalLink) ? props.type.externalLink : undefined; if (!_.isUndefined(typeNameUrlIfExists)) { typeName = ( <a @@ -162,41 +189,31 @@ export function Type(props: TypeProps): any { className="text-decoration-none" style={{ color: colors.lightBlueA700 }} > - {!_.isUndefined(typePrefixIfExists) ? `${typePrefixIfExists}.` : ''} {typeName} </a> ); } else if ( (isReference || isArray) && - (props.docsInfo.isPublicType(typeName as string) || !_.isUndefined(sectionNameIfExists)) + ((props.typeDefinitionByName && props.typeDefinitionByName[typeName as string]) || isExportedClassReference) ) { const id = Math.random().toString(); - const typeDefinitionAnchorId = _.isUndefined(sectionNameIfExists) - ? `${props.sectionName}-${typeName}` - : sectionNameIfExists; - let typeDefinition; - if (props.typeDefinitionByName) { - typeDefinition = props.typeDefinitionByName[typeName as string]; - } + const typeDefinitionAnchorId = isExportedClassReference + ? props.type.name + : `${constants.TYPES_SECTION_NAME}-${typeName}`; typeName = ( <ScrollLink to={typeDefinitionAnchorId} offset={0} + hashSpy={true} duration={sharedConstants.DOCS_SCROLL_DURATION_MS} containerId={sharedConstants.DOCS_CONTAINER_ID} > - {_.isUndefined(typeDefinition) || sharedUtils.isUserOnMobile() ? ( - <span - onClick={sharedUtils.setUrlHash.bind(null, typeDefinitionAnchorId)} - style={{ color: colors.lightBlueA700, cursor: 'pointer' }} - > - {typeName} - </span> + {sharedUtils.isUserOnMobile() || props.isInPopover || isExportedClassReference ? ( + <span style={{ color: colors.lightBlueA700, cursor: 'pointer' }}>{typeName}</span> ) : ( <span data-tip={true} data-for={id} - onClick={sharedUtils.setUrlHash.bind(null, typeDefinitionAnchorId)} style={{ color: colors.lightBlueA700, cursor: 'pointer', @@ -207,9 +224,11 @@ export function Type(props: TypeProps): any { <ReactTooltip type="light" effect="solid" id={id} className="typeTooltip"> <TypeDefinition sectionName={props.sectionName} - customType={typeDefinition} + customType={props.typeDefinitionByName[typeName as string]} shouldAddId={false} docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} + isInPopover={true} /> </ReactTooltip> </span> @@ -230,4 +249,6 @@ export function Type(props: TypeProps): any { )} </span> ); -} +}; + +Type.defaultProps = defaultProps; diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index c4bd7359a..8d1f88490 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -4,7 +4,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, CustomTypeChild, KindString, TypeDocTypes } from '../types'; +import { CustomType, CustomTypeChild, KindString, TypeDefinitionByName, TypeDocTypes } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; @@ -19,6 +19,8 @@ export interface TypeDefinitionProps { customType: CustomType; shouldAddId?: boolean; docsInfo: DocsInfo; + typeDefinitionByName?: TypeDefinitionByName; + isInPopover?: boolean; } export interface TypeDefinitionState { @@ -28,6 +30,7 @@ export interface TypeDefinitionState { export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDefinitionState> { public static defaultProps: Partial<TypeDefinitionProps> = { shouldAddId: true, + isInPopover: false, }; constructor(props: TypeDefinitionProps) { super(props); @@ -37,9 +40,6 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef } public render(): React.ReactNode { const customType = this.props.customType; - if (!this.props.docsInfo.isPublicType(customType.name)) { - return null; // no-op - } let typePrefix: string; let codeSnippet: React.ReactNode; @@ -47,7 +47,13 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef case KindString.Interface: typePrefix = 'Interface'; codeSnippet = ( - <Interface type={customType} sectionName={this.props.sectionName} docsInfo={this.props.docsInfo} /> + <Interface + type={customType} + sectionName={this.props.sectionName} + docsInfo={this.props.docsInfo} + typeDefinitionByName={this.props.typeDefinitionByName} + isInPopover={this.props.isInPopover} + /> ); break; @@ -77,6 +83,8 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef type={customType.type} sectionName={this.props.sectionName} docsInfo={this.props.docsInfo} + typeDefinitionByName={this.props.typeDefinitionByName} + isInPopover={this.props.isInPopover} /> ) : ( <Signature @@ -89,6 +97,8 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef shouldHideMethodName={true} shouldUseArrowSyntax={true} docsInfo={this.props.docsInfo} + typeDefinitionByName={this.props.typeDefinitionByName} + isInPopover={this.props.isInPopover} /> )} </span> @@ -103,7 +113,7 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef return ( <div id={this.props.shouldAddId ? typeDefinitionAnchorId : ''} - className="pb2" + className="pb2 pt2" style={{ overflow: 'hidden', width: '100%' }} onMouseOver={this._setAnchorVisibility.bind(this, true)} onMouseOut={this._setAnchorVisibility.bind(this, false)} diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index b37942da6..f429a34cb 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -6,72 +6,37 @@ import { ContractsByVersionByNetworkId, DocAgnosticFormat, DocsInfoConfig, - DocsInfoTypeConfigs, DocsMenu, DoxityDocObj, + GeneratedDocJson, SectionNameToMarkdownByVersion, SectionsMap, SupportedDocJson, TypeDefinitionByName, - TypeDocNode, } from './types'; import { doxityUtils } from './utils/doxity_utils'; -import { typeDocUtils } from './utils/typedoc_utils'; +import { TypeDocUtils } from './utils/typedoc_utils'; export class DocsInfo { public id: string; public type: SupportedDocJson; public displayName: string; + public packageName: string; public packageUrl: string; public menu: DocsMenu; public sections: SectionsMap; public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; - public typeConfigs: DocsInfoTypeConfigs; - private readonly _docsInfo: DocsInfoConfig; constructor(config: DocsInfoConfig) { this.id = config.id; this.type = config.type; + this.menu = config.markdownMenu; this.displayName = config.displayName; + this.packageName = config.packageName; this.packageUrl = config.packageUrl; - this.sections = config.sections; + this.sections = config.markdownSections; this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion; this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId; - this.typeConfigs = config.typeConfigs; - this._docsInfo = config; - } - public isPublicType(typeName: string): boolean { - if (_.isUndefined(this._docsInfo.typeConfigs.publicTypes)) { - return false; - } - const isPublic = _.includes(this._docsInfo.typeConfigs.publicTypes, typeName); - return isPublic; - } - public getModulePathsIfExists(sectionName: string): string[] { - const modulePathsIfExists = this._docsInfo.sectionNameToModulePath[sectionName]; - return modulePathsIfExists; - } - public getMenu(selectedVersion?: string): { [section: string]: string[] } { - if (_.isUndefined(selectedVersion) || _.isUndefined(this._docsInfo.menuSubsectionToVersionWhenIntroduced)) { - return this._docsInfo.menu; - } - - const finalMenu = _.cloneDeep(this._docsInfo.menu); - if (_.isUndefined(finalMenu.contracts)) { - return finalMenu; - } - - // TODO: refactor to include more sections then simply the `contracts` section - finalMenu.contracts = _.filter(finalMenu.contracts, (contractName: string) => { - const versionIntroducedIfExists = this._docsInfo.menuSubsectionToVersionWhenIntroduced[contractName]; - if (!_.isUndefined(versionIntroducedIfExists)) { - const doesExistInSelectedVersion = compareVersions(selectedVersion, versionIntroducedIfExists) >= 0; - return doesExistInSelectedVersion; - } else { - return true; - } - }); - return finalMenu; } public getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { const menuSubsectionsBySection = {} as MenuSubsectionsBySection; @@ -86,22 +51,38 @@ export class DocsInfo { return; // no-op } + const isExportedFunctionSection = + docSection.functions.length === 1 && + _.isEmpty(docSection.types) && + _.isEmpty(docSection.methods) && + _.isEmpty(docSection.constructors) && + _.isEmpty(docSection.properties) && + _.isEmpty(docSection.events); + if (!_.isUndefined(this.sections.types) && sectionName === this.sections.types) { const sortedTypesNames = _.sortBy(docSection.types, 'name'); const typeNames = _.map(sortedTypesNames, t => t.name); menuSubsectionsBySection[sectionName] = typeNames; + } else if (isExportedFunctionSection) { + // Noop so that we don't have the method listed underneath itself. } else { let eventNames: string[] = []; if (!_.isUndefined(docSection.events)) { const sortedEventNames = _.sortBy(docSection.events, 'name'); eventNames = _.map(sortedEventNames, m => m.name); } - const sortedMethodNames = _.sortBy(docSection.methods, 'name'); - const methodNames = _.map(sortedMethodNames, m => m.name); - menuSubsectionsBySection[sectionName] = [...methodNames, ...eventNames]; + const propertiesSortedByName = _.sortBy(docSection.properties, 'name'); + const propertyNames = _.map(propertiesSortedByName, m => m.name); + const methodsSortedByName = _.sortBy(docSection.methods, 'name'); + const methodNames = _.map(methodsSortedByName, m => m.name); const sortedFunctionNames = _.sortBy(docSection.functions, 'name'); const functionNames = _.map(sortedFunctionNames, m => m.name); - menuSubsectionsBySection[sectionName] = [...eventNames, ...functionNames, ...methodNames]; + menuSubsectionsBySection[sectionName] = [ + ...eventNames, + ...propertyNames, + ...functionNames, + ...methodNames, + ]; } }); return menuSubsectionsBySection; @@ -115,14 +96,12 @@ export class DocsInfo { const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name') as any; return typeDefinitionByName; } - public isVisibleConstructor(sectionName: string): boolean { - return _.includes(this._docsInfo.visibleConstructors, sectionName); - } - public convertToDocAgnosticFormat(docObj: DoxityDocObj | TypeDocNode): DocAgnosticFormat { + public convertToDocAgnosticFormat(docObj: DoxityDocObj | GeneratedDocJson): DocAgnosticFormat { if (this.type === SupportedDocJson.Doxity) { return doxityUtils.convertToDocAgnosticFormat(docObj as DoxityDocObj); } else { - return typeDocUtils.convertToDocAgnosticFormat(docObj as TypeDocNode, this); + const typeDocUtils = new TypeDocUtils(docObj as GeneratedDocJson, this); + return typeDocUtils.convertToDocAgnosticFormat(); } } } diff --git a/packages/react-docs/src/index.ts b/packages/react-docs/src/index.ts index 30f5011b7..e4424f679 100644 --- a/packages/react-docs/src/index.ts +++ b/packages/react-docs/src/index.ts @@ -15,6 +15,14 @@ export { Type } from './components/type'; export { DocsInfo } from './docs_info'; -export { DocsInfoConfig, DocAgnosticFormat, DoxityDocObj, DocsMenu, SupportedDocJson, TypeDocNode } from './types'; +export { + DocsInfoConfig, + DocAgnosticFormat, + DoxityDocObj, + DocsMenu, + SupportedDocJson, + TypeDocNode, + GeneratedDocJson, +} from './types'; export { constants } from './utils/constants'; diff --git a/packages/react-docs/src/monorepo_scripts/postpublish.ts b/packages/react-docs/src/monorepo_scripts/postpublish.ts deleted file mode 100644 index dcb99d0f7..000000000 --- a/packages/react-docs/src/monorepo_scripts/postpublish.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { postpublishUtils } from '@0xproject/monorepo-scripts'; - -import * as packageJSON from '../package.json'; -import * as tsConfigJSON from '../tsconfig.json'; - -const cwd = `${__dirname}/..`; -// tslint:disable-next-line:no-floating-promises -postpublishUtils.runAsync(packageJSON, tsConfigJSON, cwd); diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index cbc774c2e..7fd785e32 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -4,24 +4,14 @@ export interface SectionNameToMarkdownByVersion { export interface DocsInfoConfig { id: string; + packageName: string; type: SupportedDocJson; displayName: string; packageUrl: string; - menu: DocsMenu; - sections: SectionsMap; + markdownMenu: DocsMenu; + markdownSections: SectionsMap; sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; - visibleConstructors: string[]; - sectionNameToModulePath?: { [sectionName: string]: string[] }; - menuSubsectionToVersionWhenIntroduced?: { [sectionName: string]: string }; contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; - typeConfigs?: DocsInfoTypeConfigs; -} - -export interface DocsInfoTypeConfigs { - typeNameToExternalLink?: { [typeName: string]: string }; - publicTypes?: string[]; - typeNameToPrefix?: { [typeName: string]: string }; - typeNameToDocSection?: { [typeName: string]: string }; } export interface DocsMenu { @@ -40,6 +30,7 @@ export interface TypeDocType { typeArguments?: TypeDocType[]; declaration: TypeDocNode; elementType?: TypeDocType; + indexSignature?: TypeDocNode; } export interface TypeDocFlags { @@ -69,7 +60,7 @@ export interface TypeDocNode { returns?: string; declaration: TypeDocNode; flags?: TypeDocFlags; - indexSignature?: TypeDocNode | TypeDocNode[]; // TypeDocNode in TypeDoc <V0.9.0, TypeDocNode[] in >V0.9.0 + indexSignature?: TypeDocNode; signatures?: TypeDocNode[]; parameters?: TypeDocNode[]; typeParameter?: TypeDocNode[]; @@ -115,8 +106,9 @@ export interface DocSection { methods: Array<TypescriptMethod | SolidityMethod>; properties: Property[]; types: CustomType[]; - functions?: TypescriptFunction[]; + functions: TypescriptFunction[]; events?: Event[]; + externalExportToLink?: ExternalExportToLink; } export interface TypescriptMethod extends BaseMethod { @@ -128,6 +120,7 @@ export interface TypescriptMethod extends BaseMethod { export interface TypescriptFunction extends BaseFunction { source?: Source; typeParameter?: TypeParameter; + callPath: string; } export interface SolidityMethod extends BaseMethod { @@ -157,10 +150,13 @@ export interface Type { name: string; typeDocType: TypeDocTypes; value?: string; + isExportedClassReference?: boolean; typeArguments?: Type[]; elementType?: ElementType; types?: Type[]; method?: TypescriptMethod; + indexSignature?: IndexSignature; + externalLink?: string; } export interface ElementType { @@ -207,6 +203,7 @@ export interface Property { type: Type; source?: Source; comment?: string; + callPath?: string; } export interface BaseMethod { @@ -292,3 +289,28 @@ export enum AbiTypes { Function = 'function', Event = 'event', } + +export interface ExportNameToTypedocNames { + [exportName: string]: string[]; +} + +export interface ExternalTypeToLink { + [externalTypeName: string]: string; +} + +export interface ExternalExportToLink { + [externalExport: string]: string; +} + +export interface Metadata { + exportPathToTypedocNames: ExportNameToTypedocNames; + exportPathOrder: string[]; + externalTypeToLink: ExternalTypeToLink; + externalExportToLink: ExternalExportToLink; +} + +export interface GeneratedDocJson { + version: string; + metadata: Metadata; + typedocJson: TypeDocNode; +} diff --git a/packages/react-docs/src/utils/constants.ts b/packages/react-docs/src/utils/constants.ts index c3c74fd11..0b08f2c3e 100644 --- a/packages/react-docs/src/utils/constants.ts +++ b/packages/react-docs/src/utils/constants.ts @@ -2,6 +2,7 @@ import { SupportedDocJson } from '../types'; export const constants = { TYPES_SECTION_NAME: 'types', + EXTERNAL_EXPORTS_SECTION_NAME: 'external exports', TYPE_TO_SYNTAX: { [SupportedDocJson.Doxity]: 'solidity', [SupportedDocJson.TypeDoc]: 'typescript', diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index a6d938e94..76443ad81 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -7,11 +7,13 @@ import { CustomTypeChild, DocAgnosticFormat, DocSection, + ExternalExportToLink, + ExternalTypeToLink, + GeneratedDocJson, IndexSignature, KindString, Parameter, Property, - SectionsMap, Type, TypeDocNode, TypeDocType, @@ -21,8 +23,42 @@ import { TypescriptMethod, } from '../types'; -export const typeDocUtils = { - isType(entity: TypeDocNode): boolean { +import { constants } from './constants'; + +export class TypeDocUtils { + private readonly _typeDocNameOrder: string[]; + private readonly _externalTypeToLink: ExternalTypeToLink; + private readonly _externalExportToLink: ExternalExportToLink; + private readonly _docsInfo: DocsInfo; + private readonly _typeDocJson: TypeDocNode; + private readonly _classNames: string[]; + constructor(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo) { + this._docsInfo = docsInfo; + const exportPathOrder = generatedDocJson.metadata.exportPathOrder; + const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; + this._externalTypeToLink = generatedDocJson.metadata.externalTypeToLink; + this._externalExportToLink = generatedDocJson.metadata.externalExportToLink; + this._typeDocJson = generatedDocJson.typedocJson; + + // TODO: Extract the non typeDoc exports, and render them somehow + this._typeDocNameOrder = _.compact( + _.flatten( + _.map(exportPathOrder, exportPath => { + return exportPathToTypedocNames[exportPath]; + }), + ), + ); + + this._classNames = []; + _.each(this._typeDocJson.children, file => { + _.each(file.children, child => { + if (child.kindString === KindString.Class) { + this._classNames.push(child.name); + } + }); + }); + } + public isType(entity: TypeDocNode): boolean { return ( entity.kindString === KindString.Interface || entity.kindString === KindString.Function || @@ -30,20 +66,20 @@ export const typeDocUtils = { entity.kindString === KindString.Variable || entity.kindString === KindString.Enumeration ); - }, - isMethod(entity: TypeDocNode): boolean { + } + public isMethod(entity: TypeDocNode): boolean { return entity.kindString === KindString.Method; - }, - isConstructor(entity: TypeDocNode): boolean { + } + public isConstructor(entity: TypeDocNode): boolean { return entity.kindString === KindString.Constructor; - }, - isProperty(entity: TypeDocNode): boolean { + } + public isProperty(entity: TypeDocNode): boolean { return entity.kindString === KindString.Property; - }, - isPrivateOrProtectedProperty(propertyName: string): boolean { - return _.startsWith(propertyName, '_'); - }, - getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] { + } + public isUnderscorePrefixed(name: string): boolean { + return _.startsWith(name, '_'); + } + public getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] { const moduleDefinitions: TypeDocNode[] = []; const jsonModules = versionDocObj.children; _.each(jsonModules, jsonMod => { @@ -54,66 +90,87 @@ export const typeDocUtils = { }); }); return moduleDefinitions; - }, - convertToDocAgnosticFormat(typeDocJson: TypeDocNode, docsInfo: DocsInfo): DocAgnosticFormat { - const subMenus = _.values(docsInfo.getMenu()); - const orderedSectionNames = _.flatten(subMenus); + } + public convertToDocAgnosticFormat(): DocAgnosticFormat { const docAgnosticFormat: DocAgnosticFormat = {}; - _.each(orderedSectionNames, sectionName => { - const modulePathsIfExists = docsInfo.getModulePathsIfExists(sectionName); - if (_.isUndefined(modulePathsIfExists)) { - return; // no-op - } - const packageDefinitions = typeDocUtils.getModuleDefinitionsBySectionName(typeDocJson, modulePathsIfExists); - let packageDefinitionWithMergedChildren; - if (_.isEmpty(packageDefinitions)) { - return; // no-op - } else if (packageDefinitions.length === 1) { - packageDefinitionWithMergedChildren = packageDefinitions[0]; - } else { - // HACK: For now, if there are two modules to display in a single section, - // we simply concat the children. This works for our limited use-case where - // we want to display types stored in two files under a single section - packageDefinitionWithMergedChildren = packageDefinitions[0]; - for (let i = 1; i < packageDefinitions.length; i++) { - packageDefinitionWithMergedChildren.children = [ - ...packageDefinitionWithMergedChildren.children, - ...packageDefinitions[i].children, - ]; - } - } - let entities; - let packageComment = ''; - // HACK: We assume 1 exported class per file - const classChildren = _.filter(packageDefinitionWithMergedChildren.children, (child: TypeDocNode) => { - return child.kindString === KindString.Class; - }); - if (classChildren.length > 1 && sectionName !== 'types') { - throw new Error('`react-docs` only supports projects with 1 exported class per file'); - } - const isClassExport = packageDefinitionWithMergedChildren.children[0].kindString === KindString.Class; - const isObjectLiteralExport = - packageDefinitionWithMergedChildren.children[0].kindString === KindString.ObjectLiteral; - if (isClassExport) { - entities = packageDefinitionWithMergedChildren.children[0].children; - const commentObj = packageDefinitionWithMergedChildren.children[0].comment; - packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment; - } else if (isObjectLiteralExport) { - entities = packageDefinitionWithMergedChildren.children[0].children; - const commentObj = packageDefinitionWithMergedChildren.children[0].comment; - packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment; - } else { - entities = packageDefinitionWithMergedChildren.children; - } + if (!_.isEmpty(this._externalExportToLink)) { + this._docsInfo.sections[constants.EXTERNAL_EXPORTS_SECTION_NAME] = constants.EXTERNAL_EXPORTS_SECTION_NAME; + this._docsInfo.menu[constants.EXTERNAL_EXPORTS_SECTION_NAME] = [constants.EXTERNAL_EXPORTS_SECTION_NAME]; + const docSection: DocSection = { + comment: 'This package also re-exports some third-party libraries for your convenience.', + constructors: [], + methods: [], + functions: [], + properties: [], + types: [], + externalExportToLink: this._externalExportToLink, + }; + docAgnosticFormat[constants.EXTERNAL_EXPORTS_SECTION_NAME] = docSection; + } - const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); - docSection.comment = packageComment; - docAgnosticFormat[sectionName] = docSection; + const typeEntities: TypeDocNode[] = []; + _.each(this._typeDocNameOrder, typeDocName => { + const fileChildIndex = _.findIndex(this._typeDocJson.children, child => child.name === typeDocName); + const fileChild = this._typeDocJson.children[fileChildIndex]; + let sectionName: string; + _.each(fileChild.children, child => { + switch (child.kindString) { + case KindString.Class: + case KindString.ObjectLiteral: { + sectionName = child.name; + this._docsInfo.sections[sectionName] = sectionName; + this._docsInfo.menu[sectionName] = [sectionName]; + const entities = child.children; + const commentObj = child.comment; + const sectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; + const isClassOrObjectLiteral = true; + const docSection = this._convertEntitiesToDocSection( + entities, + sectionName, + isClassOrObjectLiteral, + ); + docSection.comment = sectionComment; + docAgnosticFormat[sectionName] = docSection; + break; + } + case KindString.Function: { + sectionName = child.name; + this._docsInfo.sections[sectionName] = sectionName; + this._docsInfo.menu[sectionName] = [sectionName]; + const entities = [child]; + const commentObj = child.comment; + const SectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; + const docSection = this._convertEntitiesToDocSection(entities, sectionName); + docSection.comment = SectionComment; + docAgnosticFormat[sectionName] = docSection; + break; + } + case KindString.Interface: + case KindString.Variable: + case KindString.Enumeration: + case KindString.TypeAlias: + typeEntities.push(child); + break; + default: + throw errorUtils.spawnSwitchErr('kindString', child.kindString); + } + }); }); + if (!_.isEmpty(typeEntities)) { + this._docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; + this._docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; + const docSection = this._convertEntitiesToDocSection(typeEntities, constants.TYPES_SECTION_NAME); + docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; + } + return docAgnosticFormat; - }, - _convertEntitiesToDocSection(entities: TypeDocNode[], docsInfo: DocsInfo, sectionName: string): DocSection { + } + private _convertEntitiesToDocSection( + entities: TypeDocNode[], + sectionName: string, + isClassOrObjectLiteral: boolean = false, + ): DocSection { const docSection: DocSection = { comment: '', constructors: [], @@ -128,60 +185,44 @@ export const typeDocUtils = { switch (entity.kindString) { case KindString.Constructor: isConstructor = true; - const constructor = typeDocUtils._convertMethod( - entity, - isConstructor, - docsInfo.sections, - sectionName, - docsInfo.id, - ); + const constructor = this._convertMethod(entity, isConstructor, sectionName); docSection.constructors.push(constructor); break; case KindString.Function: if (entity.flags.isExported) { - const func = typeDocUtils._convertFunction(entity, docsInfo.sections, sectionName, docsInfo.id); - docSection.functions.push(func); + const funcName = entity.signatures[0].name; + if (!this.isUnderscorePrefixed(funcName)) { + const func = this._convertFunction(entity, sectionName, isClassOrObjectLiteral); + docSection.functions.push(func); + } } break; case KindString.Method: - if (entity.flags.isPublic) { + if (entity.flags.isPublic && !this.isUnderscorePrefixed(entity.name)) { isConstructor = false; - const method = typeDocUtils._convertMethod( - entity, - isConstructor, - docsInfo.sections, - sectionName, - docsInfo.id, - ); + const method = this._convertMethod(entity, isConstructor, sectionName); docSection.methods.push(method); } break; - case KindString.Property: - if (!typeDocUtils.isPrivateOrProtectedProperty(entity.name)) { - const property = typeDocUtils._convertProperty( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - ); + case KindString.Property: { + if (!this.isUnderscorePrefixed(entity.name)) { + const property = this._convertProperty(entity, sectionName); docSection.properties.push(property); } break; + } - case KindString.Interface: case KindString.Variable: - case KindString.Enumeration: - case KindString.TypeAlias: - if (docsInfo.isPublicType(entity.name)) { - const customType = typeDocUtils._convertCustomType( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - ); + if (isClassOrObjectLiteral) { + // Render as a property + const property = this._convertProperty(entity, sectionName); + docSection.properties.push(property); + } else { + // Otherwise, render as a type + const customType = this._convertCustomType(entity, sectionName); const seenTypeNames = _.map(docSection.types, t => t.name); const isUnseen = !_.includes(seenTypeNames, customType.name); if (isUnseen) { @@ -190,6 +231,18 @@ export const typeDocUtils = { } break; + case KindString.Interface: + case KindString.Enumeration: + case KindString.TypeAlias: { + const customType = this._convertCustomType(entity, sectionName); + const seenTypeNames = _.map(docSection.types, t => t.name); + const isUnseen = !_.includes(seenTypeNames, customType.name); + if (isUnseen) { + docSection.types.push(customType); + } + break; + } + case KindString.Class: // We currently do not support more then a single class per file // except for the types section, where we ignore classes since we @@ -201,25 +254,17 @@ export const typeDocUtils = { } }); return docSection; - }, - _convertCustomType(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): CustomType { - const typeIfExists = !_.isUndefined(entity.type) - ? typeDocUtils._convertType(entity.type, sections, sectionName, docId) - : undefined; + } + private _convertCustomType(entity: TypeDocNode, sectionName: string): CustomType { + const typeIfExists = !_.isUndefined(entity.type) ? this._convertType(entity.type, sectionName) : undefined; const isConstructor = false; const methodIfExists = !_.isUndefined(entity.declaration) - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) + ? this._convertMethod(entity.declaration, isConstructor, sectionName) : undefined; const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature); - const isIndexSignatureArray = _.isArray(entity.indexSignature); - // HACK: TypeDoc Versions <0.9.0 indexSignature is of type TypeDocNode[] - // Versions >0.9.0 have it as type TypeDocNode - const indexSignature = - doesIndexSignatureExist && isIndexSignatureArray - ? (entity.indexSignature as TypeDocNode[])[0] - : (entity.indexSignature as TypeDocNode); + const indexSignature = entity.indexSignature; const indexSignatureIfExists = doesIndexSignatureExist - ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId) + ? this._convertIndexSignature(indexSignature, sectionName) : undefined; const commentIfExists = !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText) @@ -229,13 +274,13 @@ export const typeDocUtils = { const childrenIfExist = !_.isUndefined(entity.children) ? _.map(entity.children, (child: TypeDocNode) => { let childTypeIfExists = !_.isUndefined(child.type) - ? typeDocUtils._convertType(child.type, sections, sectionName, docId) + ? this._convertType(child.type, sectionName) : undefined; if (child.kindString === KindString.Method) { childTypeIfExists = { name: child.name, typeDocType: TypeDocTypes.Reflection, - method: typeDocUtils._convertMethod(child, isConstructor, sections, sectionName, docId), + method: this._convertMethod(child, isConstructor, sectionName), }; } const c: CustomTypeChild = { @@ -258,71 +303,49 @@ export const typeDocUtils = { children: childrenIfExist, }; return customType; - }, - _convertIndexSignature( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - ): IndexSignature { + } + private _convertIndexSignature(entity: TypeDocNode, sectionName: string): IndexSignature { const key = entity.parameters[0]; const indexSignature = { keyName: key.name, - keyType: typeDocUtils._convertType(key.type, sections, sectionName, docId), + keyType: this._convertType(key.type, sectionName), valueName: entity.type.name, }; return indexSignature; - }, - _convertProperty(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): Property { + } + private _convertProperty(entity: TypeDocNode, sectionName: string): Property { const source = entity.sources[0]; const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; + const isConstructor = false; + const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; + const callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); const property = { name: entity.name, - type: typeDocUtils._convertType(entity.type, sections, sectionName, docId), + type: this._convertType(entity.type, sectionName), source: { fileName: source.fileName, line: source.line, }, comment: commentIfExists, + callPath, }; return property; - }, - _convertMethod( - entity: TypeDocNode, - isConstructor: boolean, - sections: SectionsMap, - sectionName: string, - docId: string, - ): TypescriptMethod { + } + private _convertMethod(entity: TypeDocNode, isConstructor: boolean, sectionName: 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; - // 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; - if (isConstructor || entity.name === '__type') { - callPath = ''; - // TODO: Get rid of this 0x-specific logic - } else if (docId === 'ZERO_EX_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, docId); + return this._convertParameter(param, sectionName); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId); + const returnType = this._convertType(signature.type, sectionName); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + : this._convertTypeParameter(signature.typeParameter[0], sectionName); + const callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); const method = { isConstructor, isStatic, @@ -332,6 +355,10 @@ export const typeDocUtils = { source: { fileName: source.fileName, line: source.line, + callPath, + parameters, + returnType, + typeParameter, }, callPath, parameters, @@ -339,29 +366,49 @@ export const typeDocUtils = { typeParameter, }; return method; - }, - _convertFunction( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - ): TypescriptFunction { + } + private _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string): string { + // 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; + if (isConstructor || entityName === '__type') { + callPath = ''; + } else { + const prefix = isStatic ? sectionName : this._getLowercaseSectionName(sectionName); + callPath = `${prefix}.`; + } + return callPath; + } + private _getLowercaseSectionName(sectionName: string): string { + if (_.startsWith(sectionName, 'ERC')) { + return `${sectionName.slice(0, 3).toLowerCase()}${sectionName.slice(3)}`; + } + return `${sectionName[0].toLowerCase()}${sectionName.slice(1)}`; + } + private _convertFunction(entity: TypeDocNode, sectionName: string, isObjectLiteral: boolean): TypescriptFunction { const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName, docId); + return this._convertParameter(param, sectionName); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId); + const returnType = this._convertType(signature.type, sectionName); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + : this._convertTypeParameter(signature.typeParameter[0], sectionName); + let callPath = ''; + if (isObjectLiteral) { + const isConstructor = false; + const isStatic = false; + callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); + } const func = { name: signature.name, comment: hasComment ? signature.comment.shortText : undefined, returnComment: hasComment && signature.comment.returns ? signature.comment.returns : undefined, + callPath, source: { fileName: source.fileName, line: source.line, @@ -371,21 +418,16 @@ export const typeDocUtils = { typeParameter, }; return func; - }, - _convertTypeParameter( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - ): TypeParameter { - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId); + } + private _convertTypeParameter(entity: TypeDocNode, sectionName: string): TypeParameter { + const type = this._convertType(entity.type, sectionName); const parameter = { name: entity.name, type, }; return parameter; - }, - _convertParameter(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): Parameter { + } + private _convertParameter(entity: TypeDocNode, sectionName: string): Parameter { let comment = '<No comment>'; if (entity.comment && entity.comment.shortText) { comment = entity.comment.shortText; @@ -395,7 +437,7 @@ export const typeDocUtils = { const isOptional = !_.isUndefined(entity.flags.isOptional) ? entity.flags.isOptional : false; - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId); + const type = this._convertType(entity.type, sectionName); const parameter = { name: entity.name, @@ -405,19 +447,26 @@ export const typeDocUtils = { type, }; return parameter; - }, - _convertType(entity: TypeDocType, sections: SectionsMap, sectionName: string, docId: string): Type { + } + private _convertType(entity: TypeDocType, sectionName: string): Type { const typeArguments = _.map(entity.typeArguments, typeArgument => { - return typeDocUtils._convertType(typeArgument, sections, sectionName, docId); + return this._convertType(typeArgument, sectionName); }); const types = _.map(entity.types, t => { - return typeDocUtils._convertType(t, sections, sectionName, docId); + return this._convertType(t, sectionName); }); - const isConstructor = false; - const methodIfExists = !_.isUndefined(entity.declaration) - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) - : undefined; + let indexSignatureIfExists; + let methodIfExists; + const doesIndexSignatureExist = + !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); + if (doesIndexSignatureExist) { + const indexSignature = entity.declaration.indexSignature; + indexSignatureIfExists = this._convertIndexSignature(indexSignature, sectionName); + } else if (!_.isUndefined(entity.declaration)) { + const isConstructor = false; + methodIfExists = this._convertMethod(entity.declaration, isConstructor, sectionName); + } const elementTypeIfExists = !_.isUndefined(entity.elementType) ? { @@ -426,15 +475,21 @@ export const typeDocUtils = { } : undefined; - const type = { + const type: Type = { name: entity.name, value: entity.value, + isExportedClassReference: _.includes(this._classNames, entity.name), typeDocType: entity.type, typeArguments, elementType: elementTypeIfExists, types, method: methodIfExists, + indexSignature: indexSignatureIfExists, }; + const externalLinkIfExists = this._externalTypeToLink[entity.name]; + if (!_.isUndefined(externalLinkIfExists)) { + type.externalLink = externalLinkIfExists; + } return type; - }, -}; + } +} |