Add package crate docs based on readme

packages/controllers/src/lib.rs

@@ -1,3 +1,19 @@
+/*!
+This is a collection of "controllers" that we end up reimplementing in
+many contracts. I use the word "controller" similar to the MVC framework
+style, where it is an element that encapsulated business logic and data access.
+We can also directly handle some `ExecuteMsg` and `QueryMsg` variants by
+adding a sub-router to these controllers.
+
+This is the beginning of an experiment in code composition, and how best to
+reuse code among multiple contracts. We have already seen some "extend" and
+existing base contract (like `cw20-staking` extends `cw20-base`), but this
+goes for smaller scale units.
+
+Supported controllers:
+
+* Admin (`UpdateAdmin` handler, `Admin` querier, set_admin and is_admin methods)
+*/
 mod admin;
 mod claim;
 mod hooks;

packages/cw1/src/lib.rs

@@ -1,3 +1,26 @@
+/*!
+CW1 is a specification for proxy contracts based on CosmWasm.
+It is a very simple, but flexible interface designed for the case
+where one contract is meant to hold assets (or rights) on behalf of
+other contracts.
+
+The simplest example is a contract that will accept messages from
+the creator and resend them from it's address. Simply by making this
+transferable, you can then begin to transfer non-transferable assets
+(eg. staked tokens, voting power, etc).
+
+You can imagine more complex examples, such as a "1 of N" multisig,
+or conditional approval, where "sub-accounts" have the right to spend
+a limited amount of funds from this account, with a "admin account"
+retaining full control.
+
+The common denominator is that they allow you to immediately
+execute arbitrary `CosmosMsg` in the same transaction.
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw1/README.md).
+*/
+
 pub mod helpers;
 pub mod msg;
 pub mod query;

packages/cw1155/src/lib.rs

@@ -1,3 +1,19 @@
+/*!
+CW1155 is a specification for managing multiple tokens based on CosmWasm.
+The name and design is based on Ethereum's ERC1155 standard.
+
+The specification is split into multiple sections, a contract may only
+implement some of this functionality, but must implement the base.
+
+Fungible tokens and non-fungible tokens are treated equally, non-fungible tokens just have one max supply.
+
+Approval is set or unset to some operator over entire set of tokens. (More nuanced control is defined in
+[ERC1761](https://eips.ethereum.org/EIPS/eip-1761))
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw1155/README.md).
+*/
+
 pub use cw_utils::Expiration;
 
 pub use crate::event::{ApproveAllEvent, MetadataEvent, TransferEvent};

packages/cw2/src/lib.rs

@@ -1,3 +1,22 @@
+/*!
+Most of the CW* specs are focused on the *public interfaces*
+of the contract. The APIs used for `ExecuteMsg` or `QueryMsg`.
+However, when we wish to migrate or inspect smart contract info,
+we need some form of smart contract information embedded on state.
+
+This is where CW2 comes in. It specifies on special Item to
+be stored on disk by all contracts on `instantiate`.
+
+`ContractInfo` is must be stored under `"contract_info"` key which translates
+to `"636F6E74726163745F696E666F"` in hex format.
+Since the state is well defined, we do not need to support any "smart queries".
+We do provide a helper to construct a "raw query" to read the ContractInfo
+of any CW2-compliant contract.
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw2/README.md).
+*/
+
 use cosmwasm_schema::cw_serde;
 use cosmwasm_std::{Empty, Querier, QuerierWrapper, QueryRequest, StdResult, Storage, WasmQuery};
 use cw_storage_plus::Item;

packages/cw20/README.md

@@ -3,7 +3,7 @@
 CW20 is a specification for fungible tokens based on CosmWasm.
 The name and design is loosely based on Ethereum's ERC20 standard,
 but many changes have been made. The types in here can be imported by
-contracts that wish to implement this  spec, or by contracts that call
+contracts that wish to implement this spec, or by contracts that call
 to any standard cw20 contract.
 
 The specification is split into multiple sections, a contract may only

packages/cw20/src/lib.rs

@@ -1,3 +1,14 @@
+/*!
+CW20 is a specification for fungible tokens based on CosmWasm.
+The name and design is loosely based on Ethereum's ERC20 standard,
+but many changes have been made. The types in here can be imported by
+contracts that wish to implement this spec, or by contracts that call
+to any standard cw20 contract.
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md).
+*/
+
 pub use cw_utils::Expiration;
 
 pub use crate::balance::Balance;

packages/cw3/src/lib.rs

@@ -1,3 +1,14 @@
+/*!
+CW3 is a specification for voting contracts based on CosmWasm.
+It is an extension of CW1 (which served as an immediate 1 of N multisig).
+In this case, no key can immediately execute, but only propose
+a set of messages for execution. The proposal, subsequent
+approvals, and signature aggregation all happen on chain.
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw3/README.md).
+*/
+
 // mod helpers;
 mod helpers;
 mod msg;

packages/cw4/src/lib.rs

@@ -1,3 +1,24 @@
+/*!
+CW4 is a spec for storing group membership, which can be combined
+with CW3 multisigs. The purpose is to store a set of members/voters
+that can be accessed to determine permissions in another section.
+
+Since this is often deployed as a contract pair, we expect this
+contract to often be queried with `QueryRaw` and the internal
+layout of some of the data structures becomes part of the public API.
+Implementations may add more data structures, but at least
+the ones laid out here should be under the specified keys and in the
+same format.
+
+In this case, a cw3 contract could *read* an external group contract with
+no significant cost more than reading local storage. However, updating
+that group contract (if allowed), would be an external message and
+charged the instantiation overhead for each contract.
+
+For more information on this specification, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw4/README.md).
+*/
+
 mod helpers;
 mod hook;
 mod msg;

packages/storage-macro/src/lib.rs

@@ -1,3 +1,10 @@
+/*!
+Procedural macros helper for interacting with cw-storage-plus and cosmwasm-storage.
+
+For more information on this package, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/storage-macro/README.md).
+*/
+
 use proc_macro::TokenStream;
 use syn::{
     Ident,

packages/storage-plus/src/lib.rs

@@ -1,3 +1,18 @@
+/*!
+After building `cosmwasm-storage`, we realized many of the design decisions were
+limiting us and producing a lot of needless boilerplate. The decision was made to leave
+those APIs stable for anyone wanting a very basic abstraction on the KV-store and to
+build a much more powerful and complex ORM layer that can provide powerful accessors
+using complex key types, which are transparently turned into bytes.
+
+This led to a number of breaking API changes in this package of the course of several
+releases as we updated this with lots of experience, user feedback, and deep dives to harness
+the full power of generics.
+
+For more information on this package, please check out the
+[README](https://github.com/CosmWasm/cw-plus/blob/main/packages/storage-plus/README.md).
+*/
+
 mod bound;
 mod de;
 mod deque;

packages/utils/src/lib.rs

@@ -1,3 +1,11 @@
+/*!
+This is a collection of common types shared among many specs.
+For example [`Expiration`], which is embedded in many places.
+
+Types should only be added here after they are duplicated in
+a second contract, not "because we might need it"
+*/
+
 mod balance;
 mod event;
 mod expiration;