aboutsummaryrefslogtreecommitdiffstats
path: root/packages/react-docs
diff options
context:
space:
mode:
Diffstat (limited to 'packages/react-docs')
-rw-r--r--packages/react-docs/README.md6
-rw-r--r--packages/react-docs/package.json10
-rw-r--r--packages/react-docs/src/components/documentation.tsx85
-rw-r--r--packages/react-docs/src/components/event_definition.tsx7
-rw-r--r--packages/react-docs/src/components/interface.tsx33
-rw-r--r--packages/react-docs/src/components/property_block.tsx78
-rw-r--r--packages/react-docs/src/components/signature.tsx25
-rw-r--r--packages/react-docs/src/components/signature_block.tsx5
-rw-r--r--packages/react-docs/src/components/type.tsx139
-rw-r--r--packages/react-docs/src/components/type_definition.tsx22
-rw-r--r--packages/react-docs/src/docs_info.ts79
-rw-r--r--packages/react-docs/src/index.ts10
-rw-r--r--packages/react-docs/src/monorepo_scripts/postpublish.ts8
-rw-r--r--packages/react-docs/src/types.ts60
-rw-r--r--packages/react-docs/src/utils/constants.ts1
-rw-r--r--packages/react-docs/src/utils/typedoc_utils.ts440
16 files changed, 638 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..5f7601ce1 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}
/>
);
});
@@ -128,6 +167,28 @@ export function Type(props: TypeProps): any {
});
break;
+ case TypeDocTypes.Tuple:
+ const tupleTypes = _.map(type.tupleElements, t => {
+ return (
+ <Type
+ key={`type-tuple-${t.name}-${t.typeDocType}`}
+ type={t}
+ sectionName={props.sectionName}
+ typeDefinitionByName={props.typeDefinitionByName}
+ docsInfo={props.docsInfo}
+ isInPopover={props.isInPopover}
+ />
+ );
+ });
+ typeName = (
+ <div>
+ [{_.reduce(tupleTypes, (prev: React.ReactNode, curr: React.ReactNode) => {
+ return [prev, ', ', curr];
+ })}]
+ </div>
+ );
+ break;
+
default:
throw errorUtils.spawnSwitchErr('type.typeDocType', type.typeDocType);
}
@@ -140,20 +201,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 +211,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 +246,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 +271,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..f9cb5e26a 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,13 @@ export interface TypeDocType {
typeArguments?: TypeDocType[];
declaration: TypeDocNode;
elementType?: TypeDocType;
+ indexSignature?: TypeDocNode;
+ elements?: TupleElement[];
+}
+
+export interface TupleElement {
+ type: string;
+ name: string;
}
export interface TypeDocFlags {
@@ -69,7 +66,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[];
@@ -87,6 +84,7 @@ export enum TypeDocTypes {
Union = 'union',
TypeParameter = 'typeParameter',
Intersection = 'intersection',
+ Tuple = 'tuple',
Unknown = 'unknown',
}
@@ -115,8 +113,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 +127,7 @@ export interface TypescriptMethod extends BaseMethod {
export interface TypescriptFunction extends BaseFunction {
source?: Source;
typeParameter?: TypeParameter;
+ callPath: string;
}
export interface SolidityMethod extends BaseMethod {
@@ -157,10 +157,14 @@ export interface Type {
name: string;
typeDocType: TypeDocTypes;
value?: string;
+ isExportedClassReference?: boolean;
typeArguments?: Type[];
elementType?: ElementType;
types?: Type[];
method?: TypescriptMethod;
+ indexSignature?: IndexSignature;
+ externalLink?: string;
+ tupleElements?: Type[];
}
export interface ElementType {
@@ -207,6 +211,7 @@ export interface Property {
type: Type;
source?: Source;
comment?: string;
+ callPath?: string;
}
export interface BaseMethod {
@@ -292,3 +297,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..f44945369 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,41 @@ 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;
+
+ 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 +65,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 +89,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 +184,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 +230,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 +253,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 +273,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 +302,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 +354,10 @@ export const typeDocUtils = {
source: {
fileName: source.fileName,
line: source.line,
+ callPath,
+ parameters,
+ returnType,
+ typeParameter,
},
callPath,
parameters,
@@ -339,29 +365,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 +417,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 +436,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 +446,31 @@ 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;
+ let tupleElementsIfExists;
+ 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);
+ } else if (entity.type === TypeDocTypes.Tuple) {
+ tupleElementsIfExists = _.map(entity.elements, el => {
+ return { name: el.name, typeDocType: el.type as TypeDocTypes };
+ });
+ }
const elementTypeIfExists = !_.isUndefined(entity.elementType)
? {
@@ -426,15 +479,22 @@ 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,
+ tupleElements: tupleElementsIfExists,
};
+ const externalLinkIfExists = this._externalTypeToLink[entity.name];
+ if (!_.isUndefined(externalLinkIfExists)) {
+ type.externalLink = externalLinkIfExists;
+ }
return type;
- },
-};
+ }
+} // tslint:disable:max-file-line-count
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-09 21:31:37 +0800