Add rustdocs (#39)

jackcmay · web-flow · commit 9214d08be6a5 · 2020-06-17T11:25:19.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 bin
 */target/
 .vscode
+package-lock.json
diff --git a/.travis.yml b/.travis.yml
@@ -24,7 +24,6 @@ install:
   - clang-7 --version
   - nvm install node
   - node --version
-  - ./do.sh update
 
 jobs:
   include:
diff --git a/ci/memo.sh b/ci/memo.sh
@@ -4,5 +4,7 @@ cd "$(dirname "$0")/.."
 
 set -e
 
+./do.sh update
 ./do.sh build memo
+./do.sh doc memo
 ./do.sh test memo
diff --git a/ci/token.sh b/ci/token.sh
@@ -1,11 +1,21 @@
 #!/usr/bin/env bash
 
-cd "$(dirname "$0")/../token/js"
-
 set -e
 
-npm install
-npm run build:program
-npm run test
-npm run cluster:devnet
-npm run start
+(
+    cd "$(dirname "$0")/.."
+
+    ./do.sh update
+    ./do.sh build token
+    ./do.sh doc token
+    ./do.sh test token
+)
+
+(
+    cd "$(dirname "$0")/../token/js"
+
+    npm install
+    npm run build:program
+    npm run cluster:devnet
+    npm run start
+)
diff --git a/do.sh b/do.sh
@@ -69,6 +69,7 @@ perform_action() {
   update)
         mkdir -p $sdkParentDir
         ./bpf-sdk-install.sh $sdkParentDir
+        ./do.sh clean
         ;;
     dump)
         # Dump depends on tools that are not installed by default and must be installed manually
diff --git a/memo/src/lib.rs b/memo/src/lib.rs
@@ -1 +1,5 @@
+#![deny(missing_docs)]
+
+//! A simple program that accepts a string of encoded characters and verifies that it parses. Currently handles UTF-8.
+
 pub mod processor;
diff --git a/memo/src/processor.rs b/memo/src/processor.rs
@@ -1,3 +1,5 @@
+//! Program entrypoint definitions
+
 use solana_sdk::{
     account_info::AccountInfo, entrypoint, entrypoint::ProgramResult, program_error::ProgramError,
     pubkey::Pubkey,
@@ -24,18 +26,12 @@ mod tests {
         let program_id = Pubkey::new(&[0; 32]);
 
         let string = b"letters and such";
-        assert_eq!(
-            Ok(()),
-            process_instruction(&program_id, &[], string)
-        );
+        assert_eq!(Ok(()), process_instruction(&program_id, &[], string));
 
         let emoji = "🐆".as_bytes();
         let bytes = [0xF0, 0x9F, 0x90, 0x86];
         assert_eq!(emoji, bytes);
-        assert_eq!(
-            Ok(()),
-            process_instruction(&program_id, &[], &emoji)
-        );
+        assert_eq!(Ok(()), process_instruction(&program_id, &[], &emoji));
 
         let mut bad_utf8 = bytes;
         bad_utf8[3] = 0xFF; // Invalid UTF-8 byte
diff --git a/package-lock.json b/package-lock.json
diff --git a/token/Cargo.lock b/token/Cargo.lock
diff --git a/token/js/package.json b/token/js/package.json
@@ -6,15 +6,15 @@
     "type": "git",
     "url": "https://github.com/solana-labs/solana-program-library"
   },
-  "testnetDefaultChannel": "v1.2.0",
+  "testnetDefaultChannel": "v1.2.2",
   "scripts": {
     "start": "babel-node cli/main.js",
     "lint": "npm run pretty && eslint .",
     "lint:fix": "npm run lint -- --fix",
     "flow": "flow",
     "flow:watch": "watch 'flow' . --wait=1 --ignoreDirectoryPattern=/doc/",
     "lint:watch": "watch 'npm run lint:fix' . --wait=1",
-    "bpf-sdk:update": "solana-bpf-sdk-install ../../bin && npm run clean:program",
+    "bpf-sdk:update": "mkdir -p ../../bin && solana-bpf-sdk-install ../../bin && npm run clean:program",
     "build:program": "../../do.sh build token",
     "clean:program": "../../do.sh clean token",
     "test:program": "../../do.sh test token",
diff --git a/token/src/error.rs b/token/src/error.rs
@@ -1,3 +1,5 @@
+//! Error types
+
 use num_derive::FromPrimitive;
 use num_traits::FromPrimitive;
 use solana_sdk::{
@@ -7,20 +9,28 @@ use solana_sdk::{
 };
 use thiserror::Error;
 
+/// Errors that may be returned by the Token program
 #[derive(Clone, Debug, Eq, Error, FromPrimitive, PartialEq)]
 pub enum TokenError {
+    /// Insufficient funds for the operation requested.
     #[error("insufficient funds")]
     InsufficientFunds,
+    /// Token types of the provided accounts don't match.
     #[error("token mismatch")]
     TokenMismatch,
+    /// A delegate is needed but the account provided is not a delegate.
     #[error("not a delegate")]
     NotDelegate,
+    /// Owner was not a signing member of the instruction.
     #[error("no owner")]
     NoOwner,
+    /// This token's supply is fixed and new tokens cannot be minted.
     #[error("fixed supply")]
     FixedSupply,
+    /// The account cannot be initialized because it is already being used.
     #[error("AlreadyInUse")]
     AlreadyInUse,
+    /// Cannot transfer token directly to a delegate account.
     #[error("Destination is a delegate")]
     DestinationIsDelegate,
 }
diff --git a/token/src/instruction.rs b/token/src/instruction.rs
@@ -0,0 +1,77 @@
+//! Instruction types
+
+/// Specifies the financial specifics of a token.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct TokenInfo {
+    /// Total supply of tokens.
+    pub supply: u64,
+    /// Number of base 10 digits to the right of the decimal place in the total supply.
+    pub decimals: u64,
+}
+
+/// Instructions supported by the token program.
+#[repr(C)]
+#[derive(Clone, Debug, PartialEq)]
+pub enum Instruction {
+    /// Creates a new token and deposit all the newly minted tokens in an account.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [writable, signer] New token to create.
+    ///   1. [writable] Account to hold all the newly minted tokens.
+    ///   2. Optional: [] Owner of the token, if present allows further minting of tokens.
+    NewToken(TokenInfo),
+    /// Creates a new account.  The new account can either hold tokens or be a delegate
+    /// for another account.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [writable, signer]  New account being created.
+    ///   1. [] Owner of the new account.
+    ///   2. [] Token this account will be associated with.
+    ///   3. Optional: [] Source account that this account will be a delegate for.
+    NewAccount,
+    /// Transfers tokens from one account to another either directly or via a delegate.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. `[signer]` Owner of the source account.
+    ///   1. `[writable]` Source/Delegate account.
+    ///   2. `[writable]` Destination account.
+    ///   3. Optional: `[writable]` Source account if key 1 is a delegate account.
+    Transfer(u64),
+    /// Approves a delegate.  A delegate account is given the authority to transfer
+    /// another accounts tokens without the other account's owner signing the transfer.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [signer] Owner of the source account.
+    ///   1. [] Source account.
+    ///   2. [writable] Delegate account.
+    Approve(u64),
+    /// Sets a new owner of an account.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [signer] Current owner of the account.
+    ///   1. [writable] account to change the owner of.
+    ///   2. [] New owner of the account.
+    SetOwner,
+    /// Mints new tokens to an account.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [signer] Owner of the token.
+    ///   1. [writable] Token to mint.
+    ///   2. [writable] Account to mint tokens to.
+    MintTo(u64),
+    /// Burns tokens by removing them from an account and the total supply.
+    ///
+    /// # Accounts expected by this instruction:
+    ///
+    ///   0. [signer] Owner of the account to burn from.
+    ///   1. [writable] Account to burn from.
+    ///   2. [writable] Token being burned.
+    Burn(u64),
+}
diff --git a/token/src/lib.rs b/token/src/lib.rs
@@ -1,3 +1,8 @@
+#![deny(missing_docs)]
+
+//! An ERC20-like Token program for the Solana blockchain
+
 pub mod error;
+pub mod instruction;
 pub mod processor;
 pub mod state;
diff --git a/token/src/processor.rs b/token/src/processor.rs
@@ -1,3 +1,5 @@
+//! Program entrypoint definitions
+
 use crate::{error::TokenError, state::State};
 use solana_sdk::{
     account_info::AccountInfo, entrypoint, entrypoint::ProgramResult,
@@ -16,4 +18,4 @@ fn process_instruction<'a>(
         return Err(error);
     }
     Ok(())
-}
+}
diff --git a/token/src/state.rs b/token/src/state.rs

-Original file line number
+Diff line change
@@ @@ -1,3 +1,4 @@ @@
 bin
 */target/
 .vscode
 +package-lock.json