Add documentation around Commodity and CommodityContract

contracts/src/main/kotlin/com/r3corda/contracts/asset/CommodityContract.kt

@@ -28,6 +28,9 @@ val COMMODITY_PROGRAM_ID = CommodityContract()
  * differences are in representation of the underlying commodity. Issuer in this context means the party who has the
  * commodity, or is otherwise responsible for delivering the commodity on demand, and the deposit reference is use for
  * internal accounting by the issuer (it might be, for example, a warehouse and/or location within a warehouse).
+ *
+ * This is an early stage example contract used to illustrate non-cash fungible assets, and is likely to change significantly
+ * in future.
  */
 // TODO: Need to think about expiry of commodities, how to require payment of storage costs, etc.
 class CommodityContract : OnLedgerAsset<Commodity, CommodityContract.State>() {

core/src/main/kotlin/com/r3corda/core/contracts/FinanceTypes.kt

@@ -423,16 +423,26 @@ enum class NetType {
     PAYMENT
 }
 
-data class Commodity(val symbol: String,
+/**
+ * Class representing a commodity, as an equivalent to the [Currency] class. This exists purely to enable the
+ * [CommodityContract] contract, and is likely to change in future.
+ *
+ * @param commodityCode a unique code for the commodity. No specific registry for these is currently defined, although
+ * this is likely to change in future.
+ * @param displayName human readable name for the commodity.
+ * @param defaultFractionDigits the number of digits normally after the decimal point when referring to quantities of
+ * this commodity.
+ */
+data class Commodity(val commodityCode: String,
                      val displayName: String,
-                     val commodityCode: String = symbol,
                      val defaultFractionDigits: Int = 0) {
     companion object {
         private val registry = mapOf(
+                // Simple example commodity, as in http://www.investopedia.com/university/commodities/commodities14.asp
                 Pair("FCOJ", Commodity("FCOJ", "Frozen concentrated orange juice"))
         )
-        fun getInstance(symbol: String): Commodity?
+        fun getInstance(commodityCode: String): Commodity?
-                = registry[symbol]
+                = registry[commodityCode]
     }
 }
 

docs/source/contract-catalogue.rst

@@ -19,6 +19,16 @@ objects of the correct value are received by the beneficiary as part of the sett
 The cash contract supports issuing, moving and exiting (destroying) states. Note, however, that issuance cannot be part
 of the same transaction as other cash commands, in order to minimise complexity in balance verification.
 
+Cash shares a common superclass, ``OnChainAsset``, with the Commodity contract. This implements common behaviour of
+assets which can be issued, moved and exited on chain, with the subclasses handling asset-specific data types and
+behaviour.
+
+Commodity
+---------
+
+The ``Commodity`` contract is an early stage example of a non-currency contract whose states implement the ``FungibleAsset``
+interface. This is used as a proof of concept for non-cash obligations.
+
 Commercial Paper
 ----------------