CORDA-499: Dokka cleanup for 1.0 (#1579)

* Clean up Dokka comments on CordaRPCOps

* Remove use of "e.g." which Dokka will take as end of the first sentence
* Move example onto function that it actually works with
* Change comment which refers to comment above it, without any linkage, to directly describe the function
* Move implementation notes out of Dokka comment

* Make functions in CompositeSignature static

* Make contract IDs constant

* Correct contract ID in CashTestsJava

core/src/main/kotlin/net/corda/core/crypto/CompositeSignature.kt

@@ -12,6 +12,7 @@ import java.security.spec.AlgorithmParameterSpec
 class CompositeSignature : Signature(SIGNATURE_ALGORITHM) {
     companion object {
         const val SIGNATURE_ALGORITHM = "COMPOSITESIG"
+        @JvmStatic
         fun getService(provider: Provider) = Provider.Service(provider, "Signature", SIGNATURE_ALGORITHM, CompositeSignature::class.java.name, emptyList(), emptyMap())
     }
 

core/src/main/kotlin/net/corda/core/messaging/CordaRPCOps.kt

@@ -292,15 +292,9 @@ inline fun <reified T : ContractState> CordaRPCOps.vaultTrackBy(criteria: QueryC
     return vaultTrackBy(criteria, paging, sorting, T::class.java)
 }
 
-/**
+// Note that the passed in constructor function is only used for unification of other type parameters and reification of
- * These allow type safe invocations of flows from Kotlin, e.g.:
+// the Class instance of the flow. This could be changed to use the constructor function directly.
- *
+
- * val rpc: CordaRPCOps = (..)
- * rpc.startFlow(::ResolveTransactionsFlow, setOf<SecureHash>(), aliceIdentity)
- *
- * Note that the passed in constructor function is only used for unification of other type parameters and reification of
- * the Class instance of the flow. This could be changed to use the constructor function directly.
- */
 inline fun <T, reified R : FlowLogic<T>> CordaRPCOps.startFlow(
         @Suppress("UNUSED_PARAMETER")
         flowConstructor: () -> R
@@ -312,6 +306,12 @@ inline fun <T , A, reified R : FlowLogic<T>> CordaRPCOps.startFlow(
         arg0: A
 ): FlowHandle<T> = startFlowDynamic(R::class.java, arg0)
 
+/**
+ * Extension function for type safe invocation of flows from Kotlin, for example:
+ *
+ * val rpc: CordaRPCOps = (..)
+ * rpc.startFlow(::ResolveTransactionsFlow, setOf<SecureHash>(), aliceIdentity)
+ */
 inline fun <T, A, B, reified R : FlowLogic<T>> CordaRPCOps.startFlow(
         @Suppress("UNUSED_PARAMETER")
         flowConstructor: (A, B) -> R,
@@ -358,7 +358,7 @@ inline fun <T, A, B, C, D, E, F, reified R : FlowLogic<T>> CordaRPCOps.startFlow
 ): FlowHandle<T> = startFlowDynamic(R::class.java, arg0, arg1, arg2, arg3, arg4, arg5)
 
 /**
- * Same again, except this time with progress-tracking enabled.
+ * Extension function for type safe invocation of flows from Kotlin, with progress tracking enabled.
  */
 @Suppress("unused")
 inline fun <T, reified R : FlowLogic<T>> CordaRPCOps.startTrackedFlow(

docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java

@@ -328,7 +328,7 @@ public class FlowCookbookJava {
             // We can also add items using methods for the individual components:
             // DOCSTART 28
             txBuilder.addInputState(ourStateAndRef);
-            txBuilder.addOutputState(ourOutput, DummyContractKt.getDUMMY_PROGRAM_ID());
+            txBuilder.addOutputState(ourOutput, DummyContractKt.DUMMY_PROGRAM_ID);
             txBuilder.addCommand(ourCommand);
             txBuilder.addAttachment(ourAttachment);
             // DOCEND 28

finance/src/main/kotlin/net/corda/finance/contracts/CommercialPaper.kt

@@ -43,7 +43,7 @@ import java.util.*
 // TODO: Generalise the notion of an owned instrument into a superclass/supercontract. Consider composition vs inheritance.
 class CommercialPaper : Contract {
     companion object {
-        val CP_PROGRAM_ID = "net.corda.finance.contracts.CommercialPaper"
+        const val CP_PROGRAM_ID: ContractClassName = "net.corda.finance.contracts.CommercialPaper"
     }
     data class State(
             val issuance: PartyAndReference,

finance/src/main/kotlin/net/corda/finance/contracts/asset/Cash.kt

@@ -36,8 +36,7 @@ import java.util.concurrent.atomic.AtomicReference
 // Cash
 //
 
-// Just a fake program identifier for now. In a real system it could be, for instance, the hash of the program bytecode.
+const val CASH_PROGRAM_ID: ContractClassName = "net.corda.finance.contracts.asset.Cash"
-val CASH_PROGRAM_ID = "net.corda.finance.contracts.asset.Cash"
 
 /**
  * Pluggable interface to allow for different cash selection provider implementations

finance/src/main/kotlin/net/corda/finance/contracts/asset/Obligation.kt

@@ -62,8 +62,7 @@ data class MultilateralNetState<P : Any>(
 ) : NetState<P>
 
 
-// Just a fake program identifier for now. In a real system it could be, for instance, the hash of the program bytecode.
+const val OBLIGATION_PROGRAM_ID: ContractClassName = "net.corda.finance.contracts.asset.Obligation"
-val OBLIGATION_PROGRAM_ID = "net.corda.finance.contracts.asset.Obligation"
 
 /**
  * An obligation contract commits the obligor to delivering a specified amount of a fungible asset (for example the

finance/src/test/java/net/corda/finance/contracts/asset/CashTestsJava.java

@@ -19,7 +19,7 @@ public class CashTestsJava {
     private final PartyAndReference defaultIssuer = getMEGA_CORP().ref(defaultRef);
     private final Cash.State inState = new Cash.State(issuedBy(DOLLARS(1000), defaultIssuer), new AnonymousParty(getMEGA_CORP_PUBKEY()));
     private final Cash.State outState = new Cash.State(inState.getAmount(), new AnonymousParty(getMINI_CORP_PUBKEY()));
-    private final String CASH_PROGRAM_ID = CashUtilities.getCASH_PROGRAM_ID();
+    private final String CASH_PROGRAM_ID = CashUtilities.CASH_PROGRAM_ID;
 
     @Test
     public void trivial() {

samples/irs-demo/src/main/kotlin/net/corda/irs/contract/IRS.kt

@@ -18,7 +18,7 @@ import java.math.RoundingMode
 import java.time.LocalDate
 import java.util.*
 
-val IRS_PROGRAM_ID = "net.corda.irs.contract.InterestRateSwap"
+const val IRS_PROGRAM_ID = "net.corda.irs.contract.InterestRateSwap"
 
 // This is a placeholder for some types that we haven't identified exactly what they are just yet for things still in discussion
 @CordaSerializable

samples/simm-valuation-demo/src/main/kotlin/net/corda/vega/contracts/IRSState.kt

@@ -1,6 +1,7 @@
 package net.corda.vega.contracts
 
 import net.corda.core.contracts.Command
+import net.corda.core.contracts.ContractClassName
 import net.corda.core.contracts.StateAndContract
 import net.corda.core.contracts.UniqueIdentifier
 import net.corda.core.identity.AbstractParty
@@ -8,7 +9,7 @@ import net.corda.core.identity.Party
 import net.corda.core.transactions.TransactionBuilder
 import net.corda.finance.contracts.DealState
 
-val IRS_PROGRAM_ID = "net.corda.vega.contracts.OGTrade"
+const val IRS_PROGRAM_ID: ContractClassName = "net.corda.vega.contracts.OGTrade"
 
 /**
  * Represents an OpenGamma IRS between two parties. Does not implement any fixing functionality.

testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContract.kt

@@ -8,7 +8,7 @@ import net.corda.core.transactions.TransactionBuilder
 
 // The dummy contract doesn't do anything useful. It exists for testing purposes, but has to be serializable
 
-val DUMMY_PROGRAM_ID = "net.corda.testing.contracts.DummyContract"
+const val DUMMY_PROGRAM_ID: ContractClassName = "net.corda.testing.contracts.DummyContract"
 
 data class DummyContract(val blank: Any? = null) : Contract {
     interface State : ContractState {
@@ -54,7 +54,10 @@ data class DummyContract(val blank: Any? = null) : Contract {
             }
         }
 
+        @JvmStatic
         fun move(prior: StateAndRef<SingleOwnerState>, newOwner: AbstractParty) = move(listOf(prior), newOwner)
+
+        @JvmStatic
         fun move(priors: List<StateAndRef<SingleOwnerState>>, newOwner: AbstractParty): TransactionBuilder {
             require(priors.isNotEmpty())
             val priorState = priors[0].state.data

testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContractV2.kt

@@ -8,7 +8,7 @@ import net.corda.core.transactions.TransactionBuilder
 import net.corda.core.transactions.WireTransaction
 
 // The dummy contract doesn't do anything useful. It exists for testing purposes.
-val DUMMY_V2_PROGRAM_ID = "net.corda.testing.contracts.DummyContractV2"
+const val DUMMY_V2_PROGRAM_ID: ContractClassName = "net.corda.testing.contracts.DummyContractV2"
 
 /**
  * Dummy contract state for testing of the upgrade process.