Merge pull request #535 from 0xProject/fix/commentRendering

Docs: Fix Type Comment Rendering

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.

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.
  */

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;

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

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);
     },

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
             }
         ]
     },

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;
+    }
 }

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)