From a6cdc38d532b897442bac74bc3fd1735c85317ba Mon Sep 17 00:00:00 2001
From: Fabio Berger <me@fabioberger.com>
Date: Wed, 22 Aug 2018 23:25:06 +0100
Subject: Add/improve comments

---
 .../contract-wrappers/src/contract_wrappers/exchange_wrapper.ts   | 2 +-
 packages/ethereum-types/src/index.ts                              | 8 ++++----
 packages/monorepo-scripts/src/doc_gen_configs.ts                  | 6 ++++++
 3 files changed, 11 insertions(+), 5 deletions(-)

(limited to 'packages')

diff --git a/packages/contract-wrappers/src/contract_wrappers/exchange_wrapper.ts b/packages/contract-wrappers/src/contract_wrappers/exchange_wrapper.ts
index 7b1663daa..cfef0f107 100644
--- a/packages/contract-wrappers/src/contract_wrappers/exchange_wrapper.ts
+++ b/packages/contract-wrappers/src/contract_wrappers/exchange_wrapper.ts
@@ -637,7 +637,7 @@ export class ExchangeWrapper extends ContractWrapper {
     }
     /**
      * Batch version of cancelOrderAsync. Executes multiple cancels atomically in a single transaction.
-     * @param   orders                An array of orders to cancel.Optional arguments this method accepts.
+     * @param   orders                An array of orders to cancel.
      * @param   orderTransactionOpts  Optional arguments this method accepts.
      * @return  Transaction hash.
      */
diff --git a/packages/ethereum-types/src/index.ts b/packages/ethereum-types/src/index.ts
index 5ace18452..d21f69b79 100644
--- a/packages/ethereum-types/src/index.ts
+++ b/packages/ethereum-types/src/index.ts
@@ -20,7 +20,7 @@ export type ConstructorStateMutability = 'nonpayable' | 'payable';
 export type StateMutability = 'pure' | 'view' | ConstructorStateMutability;
 
 export interface MethodAbi {
-    type: 'function';
+    type: 'function'; // We hardcode this here b/c doc pages cannot render an enum value
     name: string;
     inputs: DataItem[];
     outputs: DataItem[];
@@ -30,14 +30,14 @@ export interface MethodAbi {
 }
 
 export interface ConstructorAbi {
-    type: 'constructor';
+    type: 'constructor'; // We hardcode this here b/c doc pages cannot render an enum value
     inputs: DataItem[];
     payable: boolean;
     stateMutability: ConstructorStateMutability;
 }
 
 export interface FallbackAbi {
-    type: 'fallback';
+    type: 'fallback'; // We hardcode this here b/c doc pages cannot render an enum value
     payable: boolean;
 }
 
@@ -46,7 +46,7 @@ export interface EventParameter extends DataItem {
 }
 
 export interface EventAbi {
-    type: 'event';
+    type: 'event'; // We hardcode this here b/c doc pages cannot render an enum value
     name: string;
     inputs: EventParameter[];
     anonymous: boolean;
diff --git a/packages/monorepo-scripts/src/doc_gen_configs.ts b/packages/monorepo-scripts/src/doc_gen_configs.ts
index fb6cc0886..6d7560943 100644
--- a/packages/monorepo-scripts/src/doc_gen_configs.ts
+++ b/packages/monorepo-scripts/src/doc_gen_configs.ts
@@ -1,7 +1,10 @@
 import { DocGenConfigs } from './types';
 
 export const docGenConfigs: DocGenConfigs = {
+    // Versions our doc JSON format so we can handle breaking changes  intelligently
     DOC_JSON_VERSION: '0.0.1',
+    // Some types that are exposed by our package's public interface are external types. As such, we won't
+    // be able to render their definitions. Instead we link to them using this lookup.
     EXTERNAL_TYPE_TO_LINK: {
         Array: 'https://developer.mozilla.org/pt-PT/docs/Web/JavaScript/Reference/Global_Objects/Array',
         BigNumber: 'http://mikemcl.github.io/bignumber.js',
@@ -25,6 +28,9 @@ export const docGenConfigs: DocGenConfigs = {
         Schema: 'https://github.com/tdegrunt/jsonschema/blob/v1.2.4/lib/index.d.ts#L49',
         ValidatorResult: 'https://github.com/tdegrunt/jsonschema/blob/v1.2.4/lib/helpers.js#L31',
     },
+    // Sometimes we want to hide a constructor from rendering in our docs. An example is when our library has a
+    // factory method which instantiates an instance of a class, but we don't want users instantiating it themselves
+    // and getting confused. Any class name in this list will not have it's constructor rendered in our docs.
     CLASSES_WITH_HIDDEN_CONSTRUCTORS: [
         'ERC20ProxyWrapper',
         'ERC20TokenWrapper',
-- 
cgit v1.2.3