Comprehensive docstrings as part of our renewed documentation efforts

moonworm/deployment.py

@@ -1,5 +1,7 @@
 """
-This module allows users to inspect the conditions under which a smart contract was deployed.
+Allows users to inspect the conditions under which a smart contract was deployed.
+
+The entrypoint for this functionality is [`find_deployment_block`][moonworm.deployment.find_deployment_block].
 """
 import logging
 import os
@@ -53,10 +55,27 @@ def find_deployment_block(
     web3_interval: float,
 ) -> Optional[int]:
     """
-    Note: We will assume no selfdestruct for now.
+    Performs a binary search on the blockchain to discover precisely the block when a smart contract was
+    deployed.
 
-    This means that, if the address does not currently contain code, we will assume it never contained
-    code and is therefore not a smart contract address.
+    Note: Assumes no selfdestruct. This means that, if the address does not currently contain code,
+    we will assume it never contained code and is therefore not a smart contract address.
+
+    ## Inputs
+
+    1. `web3_client`: A web3 client through which we can get block and address information on the blockchain.
+    An instance of web3.Web3.
+
+    2. `contract_address`: Address of the smart contract for which we want the deployment block. If this
+    address does not represent a smart contract, this method will return None.
+
+    3. `web3_interval`: Number of seconds to wait between requests to the web3_client. Useful if your
+    web3 provider rate limits you.
+
+    ## Outputs
+
+    Returns the block number of the block in which the smart contract was deployed. If the address does
+    not represent an existing smart contract, returns None.
     """
     log_prefix = f"find_deployment_block(web3_client, contract_address={contract_address}, web3_interval={web3_interval}) -- "
 

moonworm/generators/basic.py

@@ -1,4 +1,12 @@
-import copy
+"""
+Generates [`web3.py`](https://github.com/ethereum/web3.py)-compatible bindings to Ethereum smart contracts from their ABIs.
+
+The entrypoints to code generation are:
+
+- [`generate_contract_interface_content`][moonworm.generators.basic.generate_contract_interface_content]
+- [`generate_contract_cli_content`][moonworm.generators.basic.generate_contract_cli_content]
+"""
+
 import keyword
 import logging
 import os
@@ -479,6 +487,19 @@ def generate_argument_parser_function(abi: List[Dict[str, Any]]) -> cst.Function
 def generate_contract_interface_content(
     abi: List[Dict[str, Any]], abi_file_name: str, format: bool = True
 ) -> str:
+    """
+    Generates a Python class designed to interact with a smart contract with the given ABI.
+
+    ## Inputs
+    1. `abi`: The ABI to the smart contract. This is expected to be the Python representation of a JSON
+    list that conforms to the [Solidity ABI specification](https://docs.soliditylang.org/en/v0.8.16/abi-spec.html#json).
+    2. `abi_file_name`: Path where the contract ABI will be stored as part of codegen.
+    3. `format`: If True, uses [`black`](https://github.com/psf/black) to format the generated code before
+    returning it.
+
+    ## Outputs
+    The generated code as a string.
+    """
     contract_body = cst.Module(body=[generate_contract_class(abi)]).code
 
     content = INTERFACE_FILE_TEMPLATE.format(
@@ -496,6 +517,19 @@ def generate_contract_interface_content(
 def generate_contract_cli_content(
     abi: List[Dict[str, Any]], abi_file_name: str, format: bool = True
 ) -> str:
+    """
+    Generates a command-line interface designed to interact with a smart contract with the given ABI.
+
+    ## Inputs
+    1. `abi`: The ABI to the smart contract. This is expected to be the Python representation of a JSON
+    list that conforms to the [Solidity ABI specification](https://docs.soliditylang.org/en/v0.8.16/abi-spec.html#json).
+    2. `abi_file_name`: Path where the contract ABI will be stored as part of codegen.
+    3. `format`: If True, uses [`black`](https://github.com/psf/black) to format the generated code before
+    returning it.
+
+    ## Outputs
+    The generated code as a string.
+    """
     cli_body = cst.Module(body=[generate_argument_parser_function(abi)]).code
 
     content = CLI_FILE_TEMPLATE.format(

moonworm/generators/brownie.py

@@ -1,3 +1,9 @@
+"""
+Generates [`brownie`](https://github.com/eth-brownie/brownie)-compatible bindings to Ethereum smart contracts from their ABIs.
+
+The entrypoint to code generation is [`generate_brownie_interface`][moonworm.generators.brownie.generate_brownie_interface].
+"""
+
 import copy
 import logging
 import os
@@ -865,6 +871,17 @@ def generate_brownie_cli(
 ) -> List[cst.FunctionDef]:
     """
     Generates an argparse CLI to a brownie smart contract using the generated smart contract interface.
+
+    ## Inputs
+
+    1. `abi`: The ABI to the smart contract. This is expected to be the Python representation of a JSON
+    list that conforms to the [Solidity ABI specification](https://docs.soliditylang.org/en/v0.8.16/abi-spec.html#json).
+
+    2. `contract_name`: Name for the smart contract
+
+    ## Outputs
+
+    Concrete syntax tree representation of the generated code.
     """
     get_transaction_config_function = generate_get_transaction_config()
     add_default_arguments_function = generate_add_default_arguments()
@@ -900,6 +917,35 @@ def generate_brownie_interface(
     format: bool = True,
     prod: bool = False,
 ) -> str:
+    """
+    Generates Python code which allows you to interact with a smart contract with a given ABI, build data, and a given name.
+
+    The generated code uses the [`brownie`](https://github.com/eth-brownie/brownie) tool to interact with
+    the blockchain.
+
+    ## Inputs
+
+    1. `abi`: The ABI to the smart contract. This is expected to be the Python representation of a JSON
+    list that conforms to the [Solidity ABI specification](https://docs.soliditylang.org/en/v0.8.16/abi-spec.html#json).
+
+    2. `contract_build`: `brownie` build information for the contract (e.g. its bytecode).
+
+    3. `contract_name`: Name for the smart contract
+
+    4. `relative_path`: Path to brownie project directory (relative to target path for the generated code).
+
+    5. `cli`: Set to True if a CLI should be generated in addition to a Python class.
+
+    6. `format`: If True, uses [`black`](https://github.com/psf/black) to format the generated code before
+    returning it.
+
+    7. `prod`: If True, creates a self-contained file. Generated code will not require reference to an
+    existing brownie project at its runtime.
+
+
+    ## Outputs
+    The generated code as a string.
+    """
     contract_class = generate_brownie_contract_class(abi, contract_name)
     module_body = [contract_class]
 

moonworm/watch.py

@@ -1,9 +1,8 @@
 """
-This module implements the moonworm smart contract crawler.
+Implements the moonworm smart contract crawler.
 
 The [`watch_contract`][moonworm.watch.watch_contract] method is the entrypoint to this functionality
 and it is what powers the "moonworm watch" command.
-
 """
 
 import json