aboutsummaryrefslogtreecommitdiffstats
path: root/packages/react-docs
diff options
context:
space:
mode:
Diffstat (limited to 'packages/react-docs')
-rw-r--r--packages/react-docs/CHANGELOG.md3
-rw-r--r--packages/react-docs/src/components/documentation.tsx26
-rw-r--r--packages/react-docs/src/components/interface.tsx10
-rw-r--r--packages/react-docs/src/components/signature.tsx (renamed from packages/react-docs/src/components/method_signature.tsx)35
-rw-r--r--packages/react-docs/src/components/signature_block.tsx (renamed from packages/react-docs/src/components/method_block.tsx)24
-rw-r--r--packages/react-docs/src/components/type.tsx10
-rw-r--r--packages/react-docs/src/components/type_definition.tsx10
-rw-r--r--packages/react-docs/src/index.ts4
-rw-r--r--packages/react-docs/src/types.ts16
-rw-r--r--packages/react-docs/src/utils/typedoc_utils.ts52
10 files changed, 139 insertions, 51 deletions
diff --git a/packages/react-docs/CHANGELOG.md b/packages/react-docs/CHANGELOG.md
index 7f860739f..aa1c3c210 100644
--- a/packages/react-docs/CHANGELOG.md
+++ b/packages/react-docs/CHANGELOG.md
@@ -5,3 +5,6 @@
* Move example out into a separate sub-package
* Consolidate all `console.log` calls into `logUtils` in the `@0xproject/utils` package (#452)
* Handle `reflection` type rendering so that anonymous function type declarations render properly
+ * Rename `MethodSignature` to `Signature` and change it's props so that it can be used to render method and function signatures.
+ * Rename `MethodBlock` to `SignatureBlock` since it is not used to render method and function signature blocks.
+ * Add support for documenting exported functions.
diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx
index b46358159..67523dcc3 100644
--- a/packages/react-docs/src/components/documentation.tsx
+++ b/packages/react-docs/src/components/documentation.tsx
@@ -25,6 +25,7 @@ import {
SolidityMethod,
SupportedDocJson,
TypeDefinitionByName,
+ TypescriptFunction,
TypescriptMethod,
} from '../types';
import { constants } from '../utils/constants';
@@ -33,7 +34,7 @@ import { utils } from '../utils/utils';
import { Badge } from './badge';
import { Comment } from './comment';
import { EventDefinition } from './event_definition';
-import { MethodBlock } from './method_block';
+import { SignatureBlock } from './signature_block';
import { SourceLink } from './source_link';
import { Type } from './type';
import { TypeDefinition } from './type_definition';
@@ -216,8 +217,12 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
const sortedMethods = _.sortBy(docSection.methods, 'name');
const methodDefs = _.map(sortedMethods, method => {
- const isConstructor = false;
- return this._renderMethodBlocks(method, sectionName, isConstructor, typeDefinitionByName);
+ return this._renderSignatureBlocks(method, sectionName, typeDefinitionByName);
+ });
+
+ const sortedFunctions = _.sortBy(docSection.functions, 'name');
+ const functionDefs = _.map(sortedFunctions, func => {
+ return this._renderSignatureBlocks(func, sectionName, typeDefinitionByName);
});
const sortedEvents = _.sortBy(docSection.events, 'name');
@@ -262,6 +267,12 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
<div>{methodDefs}</div>
</div>
)}
+ {docSection.functions.length > 0 && (
+ <div>
+ <h2 style={headerStyle}>Functions</h2>
+ <div>{functionDefs}</div>
+ </div>
+ )}
{!_.isUndefined(docSection.events) &&
docSection.events.length > 0 && (
<div>
@@ -318,7 +329,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
typeDefinitionByName: TypeDefinitionByName,
): React.ReactNode {
const constructorDefs = _.map(constructors, constructor => {
- return this._renderMethodBlocks(constructor, sectionName, constructor.isConstructor, typeDefinitionByName);
+ return this._renderSignatureBlocks(constructor, sectionName, typeDefinitionByName);
});
return <div>{constructorDefs}</div>;
}
@@ -340,14 +351,13 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
</div>
);
}
- private _renderMethodBlocks(
- method: SolidityMethod | TypescriptMethod,
+ private _renderSignatureBlocks(
+ method: SolidityMethod | TypescriptFunction | TypescriptMethod,
sectionName: string,
- isConstructor: boolean,
typeDefinitionByName: TypeDefinitionByName,
): React.ReactNode {
return (
- <MethodBlock
+ <SignatureBlock
key={`method-${method.name}-${sectionName}`}
sectionName={sectionName}
method={method}
diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx
index 01f4942ef..541e164e3 100644
--- a/packages/react-docs/src/components/interface.tsx
+++ b/packages/react-docs/src/components/interface.tsx
@@ -4,7 +4,7 @@ import * as React from 'react';
import { DocsInfo } from '../docs_info';
import { CustomType, TypeDocTypes } from '../types';
-import { MethodSignature } from './method_signature';
+import { Signature } from './signature';
import { Type } from './type';
export interface InterfaceProps {
@@ -22,8 +22,12 @@ export function Interface(props: InterfaceProps) {
{property.type.typeDocType !== TypeDocTypes.Reflection ? (
<Type type={property.type} sectionName={props.sectionName} docsInfo={props.docsInfo} />
) : (
- <MethodSignature
- method={property.type.method}
+ <Signature
+ name={property.type.method.name}
+ returnType={property.type.method.returnType}
+ parameters={property.type.method.parameters}
+ typeParameter={property.type.method.typeParameter}
+ callPath={property.type.method.callPath}
sectionName={props.sectionName}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}
diff --git a/packages/react-docs/src/components/method_signature.tsx b/packages/react-docs/src/components/signature.tsx
index 1400182ea..83fb1e246 100644
--- a/packages/react-docs/src/components/method_signature.tsx
+++ b/packages/react-docs/src/components/signature.tsx
@@ -3,28 +3,33 @@ import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { DocsInfo } from '../docs_info';
-import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptMethod } from '../types';
+import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '../types';
import { constants } from '../utils/constants';
import { Type } from './type';
-export interface MethodSignatureProps {
- method: TypescriptMethod | SolidityMethod;
+export interface SignatureProps {
+ name: string;
+ returnType: TypeDef;
+ parameters: Parameter[];
sectionName: string;
shouldHideMethodName?: boolean;
shouldUseArrowSyntax?: boolean;
typeDefinitionByName?: TypeDefinitionByName;
+ typeParameter?: TypeParameter;
+ callPath?: string;
docsInfo: DocsInfo;
}
const defaultProps = {
shouldHideMethodName: false,
shouldUseArrowSyntax: false,
+ callPath: '',
};
-export const MethodSignature: React.SFC<MethodSignatureProps> = (props: MethodSignatureProps) => {
+export const Signature: React.SFC<SignatureProps> = (props: SignatureProps) => {
const sectionName = constants.TYPES_SECTION_NAME;
- const parameters = renderParameters(props.method, props.docsInfo, sectionName, props.typeDefinitionByName);
+ const parameters = renderParameters(props.parameters, props.docsInfo, sectionName, 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
@@ -51,21 +56,21 @@ export const MethodSignature: React.SFC<MethodSignatureProps> = (props: MethodSi
if (!hasMoreThenTwoParams) {
paramStringArray.pop();
}
- const methodName = props.shouldHideMethodName ? '' : props.method.name;
- const typeParameterIfExists = _.isUndefined((props.method as TypescriptMethod).typeParameter)
+ const methodName = props.shouldHideMethodName ? '' : props.name;
+ const typeParameterIfExists = _.isUndefined(props.typeParameter)
? undefined
- : renderTypeParameter(props.method, props.docsInfo, sectionName, props.typeDefinitionByName);
+ : renderTypeParameter(props.typeParameter, props.docsInfo, sectionName, props.typeDefinitionByName);
return (
<span style={{ fontSize: 15 }}>
- {props.method.callPath}
+ {props.callPath}
{methodName}
{typeParameterIfExists}({hasMoreThenTwoParams && <br />}
{paramStringArray})
- {props.method.returnType && (
+ {props.returnType && (
<span>
{props.shouldUseArrowSyntax ? ' => ' : ': '}{' '}
<Type
- type={props.method.returnType}
+ type={props.returnType}
sectionName={sectionName}
typeDefinitionByName={props.typeDefinitionByName}
docsInfo={props.docsInfo}
@@ -76,15 +81,14 @@ export const MethodSignature: React.SFC<MethodSignatureProps> = (props: MethodSi
);
};
-MethodSignature.defaultProps = defaultProps;
+Signature.defaultProps = defaultProps;
function renderParameters(
- method: TypescriptMethod | SolidityMethod,
+ parameters: Parameter[],
docsInfo: DocsInfo,
sectionName: string,
typeDefinitionByName?: TypeDefinitionByName,
) {
- const parameters = method.parameters;
const params = _.map(parameters, (p: Parameter) => {
const isOptional = p.isOptional;
const type = (
@@ -106,12 +110,11 @@ function renderParameters(
}
function renderTypeParameter(
- method: TypescriptMethod,
+ typeParameter: TypeParameter,
docsInfo: DocsInfo,
sectionName: string,
typeDefinitionByName?: TypeDefinitionByName,
) {
- const typeParameter = method.typeParameter;
const typeParam = (
<span>
{`<${typeParameter.name} extends `}
diff --git a/packages/react-docs/src/components/method_block.tsx b/packages/react-docs/src/components/signature_block.tsx
index 44a1db8af..6475d3995 100644
--- a/packages/react-docs/src/components/method_block.tsx
+++ b/packages/react-docs/src/components/signature_block.tsx
@@ -3,16 +3,16 @@ import * as _ from 'lodash';
import * as React from 'react';
import { DocsInfo } from '../docs_info';
-import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptMethod } from '../types';
+import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptFunction, TypescriptMethod } from '../types';
import { constants } from '../utils/constants';
import { typeDocUtils } from '../utils/typedoc_utils';
import { Comment } from './comment';
-import { MethodSignature } from './method_signature';
+import { Signature } from './signature';
import { SourceLink } from './source_link';
-export interface MethodBlockProps {
- method: SolidityMethod | TypescriptMethod;
+export interface SignatureBlockProps {
+ method: SolidityMethod | TypescriptFunction | TypescriptMethod;
sectionName: string;
libraryVersion: string;
typeDefinitionByName: TypeDefinitionByName;
@@ -20,7 +20,7 @@ export interface MethodBlockProps {
sourceUrl: string;
}
-export interface MethodBlockState {
+export interface SignatureBlockState {
shouldShowAnchor: boolean;
}
@@ -35,8 +35,8 @@ const styles: Styles = {
},
};
-export class MethodBlock extends React.Component<MethodBlockProps, MethodBlockState> {
- constructor(props: MethodBlockProps) {
+export class SignatureBlock extends React.Component<SignatureBlockProps, SignatureBlockState> {
+ constructor(props: SignatureBlockProps) {
super(props);
this.state = {
shouldShowAnchor: false,
@@ -56,7 +56,7 @@ export class MethodBlock extends React.Component<MethodBlockProps, MethodBlockSt
onMouseOver={this._setAnchorVisibility.bind(this, true)}
onMouseOut={this._setAnchorVisibility.bind(this, false)}
>
- {!method.isConstructor && (
+ {!(method as TypescriptMethod).isConstructor && (
<div className="flex pb2 pt2">
{(method as TypescriptMethod).isStatic && this._renderChip('Static')}
{(method as SolidityMethod).isConstant && this._renderChip('Constant')}
@@ -72,8 +72,12 @@ export class MethodBlock extends React.Component<MethodBlockProps, MethodBlockSt
</div>
)}
<code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}>
- <MethodSignature
- method={method}
+ <Signature
+ name={method.name}
+ returnType={method.returnType}
+ parameters={method.parameters}
+ typeParameter={(method as TypescriptMethod).typeParameter}
+ callPath={(method as TypescriptMethod).callPath}
sectionName={this.props.sectionName}
typeDefinitionByName={this.props.typeDefinitionByName}
docsInfo={this.props.docsInfo}
diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx
index b253f0397..fd4562ce3 100644
--- a/packages/react-docs/src/components/type.tsx
+++ b/packages/react-docs/src/components/type.tsx
@@ -9,7 +9,7 @@ import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types';
import { constants } from '../utils/constants';
import { utils } from '../utils/utils';
-import { MethodSignature } from './method_signature';
+import { Signature } from './signature';
import { TypeDefinition } from './type_definition';
const typeToSection: { [typeName: string]: string } = {
@@ -104,8 +104,12 @@ export function Type(props: TypeProps): any {
case TypeDocTypes.Reflection:
typeName = (
- <MethodSignature
- method={type.method}
+ <Signature
+ name={type.method.name}
+ returnType={type.method.returnType}
+ parameters={type.method.parameters}
+ typeParameter={type.method.typeParameter}
+ callPath={type.method.callPath}
sectionName={props.sectionName}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}
diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx
index 68ef4c465..7a1c86da5 100644
--- a/packages/react-docs/src/components/type_definition.tsx
+++ b/packages/react-docs/src/components/type_definition.tsx
@@ -11,7 +11,7 @@ import { Comment } from './comment';
import { CustomEnum } from './custom_enum';
import { Enum } from './enum';
import { Interface } from './interface';
-import { MethodSignature } from './method_signature';
+import { Signature } from './signature';
import { Type } from './type';
export interface TypeDefinitionProps {
@@ -79,8 +79,12 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
docsInfo={this.props.docsInfo}
/>
) : (
- <MethodSignature
- method={customType.type.method}
+ <Signature
+ name={customType.type.method.name}
+ returnType={customType.type.method.returnType}
+ parameters={customType.type.method.parameters}
+ typeParameter={customType.type.method.typeParameter}
+ callPath={customType.type.method.callPath}
sectionName={this.props.sectionName}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}
diff --git a/packages/react-docs/src/index.ts b/packages/react-docs/src/index.ts
index a62c91376..30f5011b7 100644
--- a/packages/react-docs/src/index.ts
+++ b/packages/react-docs/src/index.ts
@@ -7,8 +7,8 @@ export { Documentation } from './components/documentation';
export { Enum } from './components/enum';
export { EventDefinition } from './components/event_definition';
export { Interface } from './components/interface';
-export { MethodBlock } from './components/method_block';
-export { MethodSignature } from './components/method_signature';
+export { SignatureBlock } from './components/signature_block';
+export { Signature } from './components/signature';
export { SourceLink } from './components/source_link';
export { TypeDefinition } from './components/type_definition';
export { Type } from './components/type';
diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts
index d192af313..2a300c164 100644
--- a/packages/react-docs/src/types.ts
+++ b/packages/react-docs/src/types.ts
@@ -42,6 +42,7 @@ export interface TypeDocFlags {
isStatic?: boolean;
isOptional?: boolean;
isPublic?: boolean;
+ isExported?: boolean;
}
export interface TypeDocGroup {
@@ -96,6 +97,7 @@ export enum KindString {
Variable = 'Variable',
Function = 'Function',
Enumeration = 'Enumeration',
+ Class = 'Class',
}
export interface DocAgnosticFormat {
@@ -108,6 +110,7 @@ export interface DocSection {
methods: Array<TypescriptMethod | SolidityMethod>;
properties: Property[];
types: CustomType[];
+ functions?: TypescriptFunction[];
events?: Event[];
}
@@ -117,6 +120,11 @@ export interface TypescriptMethod extends BaseMethod {
typeParameter?: TypeParameter;
}
+export interface TypescriptFunction extends BaseFunction {
+ source?: Source;
+ typeParameter?: TypeParameter;
+}
+
export interface SolidityMethod extends BaseMethod {
isConstant?: boolean;
isPayable?: boolean;
@@ -205,6 +213,14 @@ export interface BaseMethod {
comment?: string;
}
+export interface BaseFunction {
+ name: string;
+ returnComment?: string | undefined;
+ parameters: Parameter[];
+ returnType: Type;
+ comment?: string;
+}
+
export interface TypeDefinitionByName {
[typeName: string]: CustomType;
}
diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts
index e4cea1e40..4c7617234 100644
--- a/packages/react-docs/src/utils/typedoc_utils.ts
+++ b/packages/react-docs/src/utils/typedoc_utils.ts
@@ -15,6 +15,7 @@ import {
TypeDocNode,
TypeDocType,
TypeParameter,
+ TypescriptFunction,
TypescriptMethod,
} from '../types';
import { utils } from '../utils/utils';
@@ -81,17 +82,16 @@ export const typeDocUtils = {
}
}
- // Since the `types.ts` file is the only file that does not export a module/class but
- // instead has each type export itself, we do not need to go down two levels of nesting
- // for it.
let entities;
let packageComment = '';
- if (sectionName === docsInfo.sections.types) {
- entities = packageDefinitionWithMergedChildren.children;
- } else {
+ // HACK: We assume 1 exported class per file
+ const isClassExport = packageDefinitionWithMergedChildren.children[0].kindString === KindString.Class;
+ if (isClassExport) {
entities = packageDefinitionWithMergedChildren.children[0].children;
const commentObj = packageDefinitionWithMergedChildren.children[0].comment;
packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment;
+ } else {
+ entities = packageDefinitionWithMergedChildren.children;
}
const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName);
@@ -105,6 +105,7 @@ export const typeDocUtils = {
comment: '',
constructors: [],
methods: [],
+ functions: [],
properties: [],
types: [],
};
@@ -124,6 +125,13 @@ export const typeDocUtils = {
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);
+ }
+ break;
+
case KindString.Method:
if (entity.flags.isPublic) {
isConstructor = false;
@@ -303,6 +311,38 @@ export const typeDocUtils = {
};
return method;
},
+ _convertFunction(
+ entity: TypeDocNode,
+ sections: SectionsMap,
+ sectionName: string,
+ docId: string,
+ ): 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);
+ });
+ const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId);
+ const typeParameter = _.isUndefined(signature.typeParameter)
+ ? undefined
+ : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId);
+
+ const func = {
+ name: signature.name,
+ comment: hasComment ? signature.comment.shortText : undefined,
+ returnComment: hasComment && signature.comment.returns ? signature.comment.returns : undefined,
+ source: {
+ fileName: source.fileName,
+ line: source.line,
+ },
+ parameters,
+ returnType,
+ typeParameter,
+ };
+ return func;
+ },
_convertTypeParameter(
entity: TypeDocNode,
sections: SectionsMap,
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-16 00:21:15 +0800