aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFabio Berger <me@fabioberger.com>2018-04-18 17:19:27 +0800
committerGitHub <noreply@github.com>2018-04-18 17:19:27 +0800
commitf6f2991a442da156a3dbdeca84683a6c9f46d0e1 (patch)
tree4951024bfba56d5c3268556c4d4e2ca0ab4f6d17
parent823f2db09fba8f19806ba3fa4bd679e12a58be3f (diff)
parent4ea222bbffd7a378712320a2f366d5bbee5920af (diff)
downloaddexon-0x-contracts-f6f2991a442da156a3dbdeca84683a6c9f46d0e1.tar.gz
dexon-0x-contracts-f6f2991a442da156a3dbdeca84683a6c9f46d0e1.tar.zst
dexon-0x-contracts-f6f2991a442da156a3dbdeca84683a6c9f46d0e1.zip
Merge pull request #535 from 0xProject/fix/commentRendering
Docs: Fix Type Comment Rendering
-rw-r--r--PULL_REQUEST_TEMPLATE.md3
-rw-r--r--packages/0x.js/src/order_watcher/event_watcher.ts2
-rw-r--r--packages/0x.js/src/types.ts24
-rw-r--r--packages/connect/src/types.ts4
-rw-r--r--packages/contracts/util/crypto.ts16
-rw-r--r--packages/react-docs/CHANGELOG.json4
-rw-r--r--packages/react-docs/src/components/type_definition.tsx43
-rw-r--r--packages/subproviders/src/types.ts9
8 files changed, 75 insertions, 30 deletions
diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
index 481b1d536..8752069db 100644
--- a/PULL_REQUEST_TEMPLATE.md
+++ b/PULL_REQUEST_TEMPLATE.md
@@ -36,7 +36,6 @@
* [ ] Change requires a change to the documentation.
* [ ] Added tests to cover my changes.
-* [ ] Added new entries to the relevant CHANGELOGs.
-* [ ] Updated the new versions of the changed packages in the relevant CHANGELOGs.
+* [ ] Added new entries to the relevant CHANGELOG.jsons.
* [ ] Labeled this PR with the 'WIP' label if it is a work in progress.
* [ ] Labeled this PR with the labels corresponding to the changed package.
diff --git a/packages/0x.js/src/order_watcher/event_watcher.ts b/packages/0x.js/src/order_watcher/event_watcher.ts
index 47bbd5b2e..de5a99a46 100644
--- a/packages/0x.js/src/order_watcher/event_watcher.ts
+++ b/packages/0x.js/src/order_watcher/event_watcher.ts
@@ -13,7 +13,7 @@ enum LogEventState {
Added,
}
-/*
+/**
* The EventWatcher watches for blockchain events at the specified block confirmation
* depth.
*/
diff --git a/packages/0x.js/src/types.ts b/packages/0x.js/src/types.ts
index d1c643a57..151204928 100644
--- a/packages/0x.js/src/types.ts
+++ b/packages/0x.js/src/types.ts
@@ -154,13 +154,13 @@ export interface OrderFillRequest {
export type AsyncMethod = (...args: any[]) => Promise<any>;
export type SyncMethod = (...args: any[]) => any;
-/*
- * orderExpirationCheckingIntervalMs: How often to check for expired orders. Default: 50
- * eventPollingIntervalMs: How often to poll the Ethereum node for new events. Default: 200
+/**
+ * orderExpirationCheckingIntervalMs: How often to check for expired orders. Default=50.
+ * eventPollingIntervalMs: How often to poll the Ethereum node for new events. Default=200.
* expirationMarginMs: Amount of time before order expiry that you'd like to be notified
- * of an orders expiration. Default: 0
- * cleanupJobIntervalMs: How often to run a cleanup job which revalidates all the orders. Defaults: 1h
- * stateLayer: Optional blockchain state layer OrderWatcher will monitor for new events. Default: latest
+ * of an orders expiration. Default=0.
+ * cleanupJobIntervalMs: How often to run a cleanup job which revalidates all the orders. Default=1hr.
+ * stateLayer: Optional blockchain state layer OrderWatcher will monitor for new events. Default=latest.
*/
export interface OrderStateWatcherConfig {
orderExpirationCheckingIntervalMs?: number;
@@ -170,7 +170,7 @@ export interface OrderStateWatcherConfig {
stateLayer: BlockParamLiteral;
}
-/*
+/**
* networkId: The id of the underlying ethereum network your provider is connected to. (1-mainnet, 3-ropsten, 4-rinkeby, 42-kovan, 50-testrpc)
* gasPrice: Gas price to use with every transaction
* exchangeContractAddress: The address of an exchange contract to use
@@ -201,7 +201,7 @@ export interface Artifact {
};
}
-/*
+/**
* expectedFillTakerTokenAmount: If specified, the validation method will ensure that the
* supplied order maker has a sufficient allowance/balance to fill this amount of the order's
* takerTokenAmount. If not specified, the validation method ensures that the maker has a sufficient
@@ -211,7 +211,7 @@ export interface ValidateOrderFillableOpts {
expectedFillTakerTokenAmount?: BigNumber;
}
-/*
+/**
* defaultBlock: The block up to which to query the blockchain state. Setting this to a historical block number
* let's the user query the blockchain's state at an arbitrary point in time. In order for this to work, the
* backing Ethereum node must keep the entire historical state of the chain (e.g setting `--pruning=archive`
@@ -221,7 +221,7 @@ export interface MethodOpts {
defaultBlock?: BlockParam;
}
-/*
+/**
* gasPrice: Gas price in Wei to use for a transaction
* gasLimit: The amount of gas to send with a transaction
*/
@@ -230,9 +230,9 @@ export interface TransactionOpts {
gasLimit?: number;
}
-/*
+/**
* shouldValidate: Flag indicating whether the library should make attempts to validate a transaction before
- * broadcasting it. For example, order has a valid signature, maker has sufficient funds, etc. Default: true
+ * broadcasting it. For example, order has a valid signature, maker has sufficient funds, etc. Default=true.
*/
export interface OrderTransactionOpts extends TransactionOpts {
shouldValidate?: boolean;
diff --git a/packages/connect/src/types.ts b/packages/connect/src/types.ts
index 5c344e328..b0467f22a 100644
--- a/packages/connect/src/types.ts
+++ b/packages/connect/src/types.ts
@@ -15,14 +15,14 @@ export interface OrderbookChannel {
close: () => void;
}
-/*
+/**
* heartbeatInterval: Interval in milliseconds that the orderbook channel should ping the underlying websocket. Default: 15000
*/
export interface WebSocketOrderbookChannelConfig {
heartbeatIntervalMs?: number;
}
-/*
+/**
* baseTokenAddress: The address of token designated as the baseToken in the currency pair calculation of price
* quoteTokenAddress: The address of token designated as the quoteToken in the currency pair calculation of price
* snapshot: If true, a snapshot of the orderbook will be sent before the updates to the orderbook
diff --git a/packages/contracts/util/crypto.ts b/packages/contracts/util/crypto.ts
index 97b8f5643..810072d2f 100644
--- a/packages/contracts/util/crypto.ts
+++ b/packages/contracts/util/crypto.ts
@@ -4,14 +4,14 @@ import ethUtil = require('ethereumjs-util');
import * as _ from 'lodash';
export const crypto = {
- /*
- * We convert types from JS to Solidity as follows:
- * BigNumber -> uint256
- * number -> uint8
- * string -> string
- * boolean -> bool
- * valid Ethereum address -> address
- */
+ /**
+ * We convert types from JS to Solidity as follows:
+ * BigNumber -> uint256
+ * number -> uint8
+ * string -> string
+ * boolean -> bool
+ * valid Ethereum address -> address
+ */
solSHA3(args: any[]): Buffer {
return crypto._solHash(args, ABI.soliditySHA3);
},
diff --git a/packages/react-docs/CHANGELOG.json b/packages/react-docs/CHANGELOG.json
index 951ed84e0..0b0d6bdc8 100644
--- a/packages/react-docs/CHANGELOG.json
+++ b/packages/react-docs/CHANGELOG.json
@@ -9,6 +9,10 @@
{
"note": "Added support for rendering nested function types within interface types",
"pr": 519
+ },
+ {
+ "note": "Improve type comment rendering",
+ "pr": 535
}
]
},
diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx
index 7a1c86da5..605b58fbd 100644
--- a/packages/react-docs/src/components/type_definition.tsx
+++ b/packages/react-docs/src/components/type_definition.tsx
@@ -122,7 +122,9 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
</pre>
</div>
<div style={{ maxWidth: 620 }}>
- {customType.comment && <Comment comment={customType.comment} className="py2" />}
+ {customType.comment && (
+ <Comment comment={this._formatComment(customType.comment)} className="py2" />
+ )}
</div>
</div>
);
@@ -132,4 +134,43 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
shouldShowAnchor,
});
}
+ /**
+ * Type definition comments usually describe the type as a whole or the individual
+ * properties within the type. Since TypeDoc just treats these comments simply as
+ * one paragraph, we do some additional formatting so that we can display individual
+ * property comments on their own lines.
+ * E.g:
+ * Interface SomeConfig
+ * {
+ * networkId: number,
+ * derivationPath: string,
+ * }
+ * networkId: The ethereum networkId to set as the chainId from EIP155
+ * derivationPath: Initial derivation path to use e.g 44'/60'/0'
+ *
+ * Each property description should be on a new line.
+ */
+ private _formatComment(text: string) {
+ const NEW_LINE_REGEX = /(\r\n|\n|\r)/gm;
+ const sanitizedText = text.replace(NEW_LINE_REGEX, ' ');
+ const PROPERTY_DESCRIPTION_DIVIDER = ':';
+ if (!_.includes(sanitizedText, PROPERTY_DESCRIPTION_DIVIDER)) {
+ return sanitizedText;
+ }
+ const segments = sanitizedText.split(PROPERTY_DESCRIPTION_DIVIDER);
+ _.each(segments, (s: string, i: number) => {
+ if (i === 0) {
+ segments[i] = `**${s}**`;
+ return;
+ } else if (i === segments.length - 1) {
+ return;
+ }
+ const words = s.split(' ');
+ const property = words[words.length - 1];
+ words[words.length - 1] = `\n\n**${property}**`;
+ segments[i] = words.join(' ');
+ });
+ const final = segments.join(PROPERTY_DESCRIPTION_DIVIDER);
+ return final;
+ }
}
diff --git a/packages/subproviders/src/types.ts b/packages/subproviders/src/types.ts
index 74ecec23b..30a3b4a4e 100644
--- a/packages/subproviders/src/types.ts
+++ b/packages/subproviders/src/types.ts
@@ -6,7 +6,8 @@ export interface LedgerCommunicationClient {
close: () => Promise<void>;
}
-/*
+/**
+ * Elliptic Curve signature
* The LedgerEthereumClient sends Ethereum-specific requests to the Ledger Nano S
* It uses an internal LedgerCommunicationClient to relay these requests. Currently
* NodeJs and Browser communication are supported.
@@ -32,7 +33,7 @@ export interface ECSignatureString {
export type LedgerEthereumClientFactoryAsync = () => Promise<LedgerEthereumClient>;
-/*
+/**
* networkId: The ethereum networkId to set as the chainId from EIP155
* ledgerConnectionType: Environment in which you wish to connect to Ledger (nodejs or browser)
* derivationPath: Initial derivation path to use e.g 44'/60'/0'
@@ -45,7 +46,7 @@ export interface LedgerSubproviderConfigs {
accountFetchingConfigs?: AccountFetchingConfigs;
}
-/*
+/**
* addressSearchLimit: The maximum number of addresses to search through, defaults to 1000
* numAddressesToReturn: Number of addresses to return from 'eth_accounts' call
* shouldAskForOnDeviceConfirmation: Whether you wish to prompt the user on their Ledger
@@ -57,7 +58,7 @@ export interface AccountFetchingConfigs {
shouldAskForOnDeviceConfirmation?: boolean;
}
-/*
+/**
* mnemonic: The string mnemonic seed
* addressSearchLimit: The maximum number of addresses to search through, defaults to 1000
* baseDerivationPath: The base derivation path (e.g 44'/60'/0'/0)