From 59d3cbdeced241a308896b16997c6c84defcdea9 Mon Sep 17 00:00:00 2001
From: Ross Nicoll <ross.nicoll@r3cev.com>
Date: Tue, 23 Aug 2016 17:38:59 +0100
Subject: [PATCH] Add documentation around Commodity and CommodityContract

---
 .../contracts/asset/CommodityContract.kt       |  3 +++
 .../com/r3corda/core/contracts/FinanceTypes.kt | 18 ++++++++++++++----
 docs/source/contract-catalogue.rst             | 10 ++++++++++
 3 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/contracts/src/main/kotlin/com/r3corda/contracts/asset/CommodityContract.kt b/contracts/src/main/kotlin/com/r3corda/contracts/asset/CommodityContract.kt
index 28e07cdde3..f576930108 100644
--- a/contracts/src/main/kotlin/com/r3corda/contracts/asset/CommodityContract.kt
+++ b/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>() {
diff --git a/core/src/main/kotlin/com/r3corda/core/contracts/FinanceTypes.kt b/core/src/main/kotlin/com/r3corda/core/contracts/FinanceTypes.kt
index a875ad6463..c147080889 100644
--- a/core/src/main/kotlin/com/r3corda/core/contracts/FinanceTypes.kt
+++ b/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?
-                = registry[symbol]
+        fun getInstance(commodityCode: String): Commodity?
+                = registry[commodityCode]
     }
 }
 
diff --git a/docs/source/contract-catalogue.rst b/docs/source/contract-catalogue.rst
index 11f3b1302b..5a38928995 100644
--- a/docs/source/contract-catalogue.rst
+++ b/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
 ----------------