ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-18 20:47:57 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Clean up of Dokka comments (#1632)

Browse Source 
* Remove use of @see as a cross-reference to actual docs; this is inappropriate (it reflects "See Also", not "See Other"), and often longer than having the actual documentation in place.
* Correct syntactical errors in docs
* Correct "@returns" to "@return"
* Add note about currencies with 3 decimal places
This commit is contained in:
Ross Nicoll 2017-09-28 17:42:32 +01:00 committed by GitHub
parent 2aaeb4c0b5
commit 89ef4034c0
8 changed files with 48 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
core/src/main/kotlin/net/corda/core/contracts/Amount.kt
View File

@ -21,7 +21,8 @@ interface TokenizableAssetInfo {
* Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest
* representable units. The nominal quantity represented by each individual token is equal to the [displayTokenSize].
* The scale property of the [displayTokenSize] should correctly reflect the displayed decimal places and is used
* when rounding conversions from indicative/displayed amounts in [BigDecimal] to Amount occur via the Amount.fromDecimal method.
* when rounding conversions from indicative/displayed amounts in [BigDecimal] to Amount occur via the
* [Amount.fromDecimal] method.
*
* Amounts of different tokens *do not mix* and attempting to add or subtract two amounts of different currencies
* will throw [IllegalArgumentException]. Amounts may not be negative. Amounts are represented internally using a signed
@ -29,10 +30,11 @@ interface TokenizableAssetInfo {
* multiplication are overflow checked and will throw [ArithmeticException] if the operation would have caused integer
* overflow.
*
* @property quantity the number of tokens as a Long value.
* @property displayTokenSize the nominal display unit size of a single token, potentially with trailing decimal display places if the scale parameter is non-zero.
* @property token an instance of type T, usually a singleton.
* @param T the type of the token, for example [Currency]. T should implement TokenizableAssetInfo if automatic conversion to/from a display format is required.
* @property quantity the number of tokens as a long value.
* @property displayTokenSize the nominal display unit size of a single token, potentially with trailing decimal display
* places if the scale parameter is non-zero.
* @property token the type of token this is an amount of. This is usually a singleton.
* @param T the type of the token, for example [Currency]. T should implement [TokenizableAssetInfo] if automatic conversion to/from a display format is required.
*/
@CordaSerializable
data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal, val token: T) : Comparable<Amount<T>> {
@ -40,11 +42,10 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
companion object {
/**
* Build an Amount from a decimal representation. For example, with an input of "12.34 GBP",
* returns an amount with a quantity of "1234" tokens. The displayTokenSize as determined via
* getDisplayTokenSize is used to determine the conversion scaling.
* e.g. Bonds might be in nominal amounts of 100, currencies in 0.01 penny units.
* returns an amount with a quantity of "1234" tokens. The function [getDisplayTokenSize] is used to determine the
* conversion scaling, for example bonds might be in nominal amounts of 100, currencies in 0.01 penny units.
*
* @see Amount<Currency>.toDecimal
* @see Amount.toDecimal
* @throws ArithmeticException if the intermediate calculations cannot be converted to an unsigned 63-bit token amount.
*/
@JvmStatic
@ -195,6 +196,7 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
* Mixing non-identical token types will throw [IllegalArgumentException].
*
* @throws ArithmeticException if there is overflow of Amount tokens during the summation
* @throws IllegalArgumentException if mixing non-identical token types.
*/
operator fun plus(other: Amount<T>): Amount<T> {
checkToken(other)
@ -202,11 +204,11 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
}
/**
* A checked addition operator is supported to simplify netting of Amounts.
* If this leads to the Amount going negative this will throw [IllegalArgumentException].
* Mixing non-identical token types will throw [IllegalArgumentException].
* A checked subtraction operator is supported to simplify netting of Amounts.
*
* @throws ArithmeticException if there is Numeric underflow
* @throws ArithmeticException if there is numeric underflow.
* @throws IllegalArgumentException if this leads to the amount going negative, or would mix non-identical token
* types.
*/
operator fun minus(other: Amount<T>): Amount<T> {
checkToken(other)
@ -222,6 +224,8 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
* The multiplication operator is supported to allow easy calculation for multiples of a primitive Amount.
* Note this is not a conserving operation, so it may not always be correct modelling of proper token behaviour.
* N.B. Division is not supported as fractional tokens are not representable by an Amount.
*
* @throws ArithmeticException if there is overflow of Amount tokens during the multiplication.
*/
operator fun times(other: Long): Amount<T> = Amount(Math.multiplyExact(quantity, other), displayTokenSize, token)
@ -229,13 +233,15 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
* The multiplication operator is supported to allow easy calculation for multiples of a primitive Amount.
* Note this is not a conserving operation, so it may not always be correct modelling of proper token behaviour.
* N.B. Division is not supported as fractional tokens are not representable by an Amount.
*
* @throws ArithmeticException if there is overflow of Amount tokens during the multiplication.
*/
operator fun times(other: Int): Amount<T> = Amount(Math.multiplyExact(quantity, other.toLong()), displayTokenSize, token)
/**
* This method provides a token conserving divide mechanism.
* @param partitions the number of amounts to divide the current quantity into.
* @result Returns [partitions] separate Amount objects which sum to the same quantity as this Amount
* @return 'partitions' separate Amount objects which sum to the same quantity as this Amount
* and differ by no more than a single token in size.
*/
fun splitEvenly(partitions: Int): List<Amount<T>> {
@ -249,8 +255,10 @@ data class Amount<T : Any>(val quantity: Long, val displayTokenSize: BigDecimal,
/**
* Convert a currency [Amount] to a decimal representation. For example, with an amount with a quantity
* of "1234" GBP, returns "12.34". The precise representation is controlled by the displayTokenSize,
* which determines the size of a single token and controls the trailing decimal places via it's scale property.
* of "1234" GBP, returns "12.34". The precise representation is controlled by the display token size (
* from [getDisplayTokenSize]), which determines the size of a single token and controls the trailing decimal
* places via its scale property. *Note* that currencies such as the Bahraini Dinar use 3 decimal places,
* and it must not be presumed that this converts amounts to 2 decimal places.
*
* @see Amount.fromDecimal
*/

6
core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt
View File

@ -100,7 +100,7 @@ abstract class FlowLogic<out T> {
* Note that this function is not just a simple send+receive pair: it is more efficient and more correct to
* use this when you expect to do a message swap than do use [send] and then [receive] in turn.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Deprecated("Use FlowSession.sendAndReceive()", level = DeprecationLevel.WARNING)
inline fun <reified R : Any> sendAndReceive(otherParty: Party, payload: Any): UntrustworthyData<R> {
@ -116,7 +116,7 @@ abstract class FlowLogic<out T> {
* Note that this function is not just a simple send+receive pair: it is more efficient and more correct to
* use this when you expect to do a message swap than do use [send] and then [receive] in turn.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Deprecated("Use FlowSession.sendAndReceive()", level = DeprecationLevel.WARNING)
@Suspendable
@ -165,7 +165,7 @@ abstract class FlowLogic<out T> {
* verified for consistency and that all expectations are satisfied, as a malicious peer may send you subtly
* corrupted data in order to exploit your code.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Deprecated("Use FlowSession.receive()", level = DeprecationLevel.WARNING)
@Suspendable

6
core/src/main/kotlin/net/corda/core/flows/FlowSession.kt
View File

@ -69,7 +69,7 @@ abstract class FlowSession {
* Note that this function is not just a simple send+receive pair: it is more efficient and more correct to
* use this when you expect to do a message swap than do use [send] and then [receive] in turn.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Suspendable
inline fun <reified R : Any> sendAndReceive(payload: Any): UntrustworthyData<R> {
@ -84,7 +84,7 @@ abstract class FlowSession {
* Note that this function is not just a simple send+receive pair: it is more efficient and more correct to
* use this when you expect to do a message swap than do use [send] and then [receive] in turn.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Suspendable
abstract fun <R : Any> sendAndReceive(receiveType: Class<R>, payload: Any): UntrustworthyData<R>
@ -107,7 +107,7 @@ abstract class FlowSession {
* verified for consistency and that all expectations are satisfied, as a malicious peer may send you subtly
* corrupted data in order to exploit your code.
*
* @returns an [UntrustworthyData] wrapper around the received object.
* @return an [UntrustworthyData] wrapper around the received object.
*/
@Suspendable
abstract fun <R : Any> receive(receiveType: Class<R>): UntrustworthyData<R>

4
core/src/main/kotlin/net/corda/core/transactions/MerkleTransaction.kt
View File

@ -104,7 +104,7 @@ class FilteredTransaction private constructor(
* Construction of partial transaction from [WireTransaction] based on filtering.
* Note that list of nonces to be sent is updated on the fly, based on the index of the filtered tx component.
* @param filtering filtering over the whole WireTransaction.
* @returns a list of [FilteredComponentGroup] used in PartialMerkleTree calculation and verification.
* @return a list of [FilteredComponentGroup] used in PartialMerkleTree calculation and verification.
*/
private fun filterWithFun(wtx: WireTransaction, filtering: Predicate<Any>): List<FilteredComponentGroup> {
val filteredSerialisedComponents: MutableMap<Int, MutableList<OpaqueBytes>> = hashMapOf()
@ -196,7 +196,7 @@ class FilteredTransaction private constructor(
* over a transaction with the attachment that wasn't verified. Of course it depends on how you implement it, but else -> false
* should solve a problem with possible later extensions to WireTransaction.
* @param checkingFun function that performs type checking on the structure fields and provides verification logic accordingly.
* @returns false if no elements were matched on a structure or checkingFun returned false.
* @return false if no elements were matched on a structure or checkingFun returned false.
*/
fun checkWithFun(checkingFun: (Any) -> Boolean): Boolean {
val checkList = availableComponentGroups.flatten().map { checkingFun(it) }

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

@ -199,7 +199,8 @@ class Obligation<P : Any> : Contract {
/**
* A command stating that the obligor is settling some or all of the amount owed by transferring a suitable
* state object to the beneficiary. If this reduces the balance to zero, the state object is destroyed.
* @see [MoveCommand].
*
* @see MoveCommand
*/
data class Settle<P : Any>(val amount: Amount<Issued<Terms<P>>>) : CommandData

2
samples/irs-demo/src/main/kotlin/net/corda/irs/contract/IRSUtils.kt
View File

@ -52,7 +52,7 @@ open class Rate(val ratioUnit: RatioUnit? = null) {
}
/**
* @returns the hash code of the ratioUnit or zero if the ratioUnit is null, as is the case for floating rate fixings
* @return the hash code of the ratioUnit or zero if the ratioUnit is null, as is the case for floating rate fixings
* that have not yet happened. Yet-to-be fixed floating rates need to be equal such that schedules can be tested
* for equality.
*/

8
testing/test-utils/src/main/kotlin/net/corda/testing/LedgerDSLInterpreter.kt
View File

@ -127,7 +127,7 @@ class LedgerDSL<out T : TransactionDSLInterpreter, out L : LedgerDSLInterpreter<
LedgerDSLInterpreter<TransactionDSLInterpreter> by interpreter {
/**
* @see LedgerDSLInterpreter._transaction
* Creates and adds a transaction to the ledger.
*/
@JvmOverloads
fun transaction(label: String? = null, transactionBuilder: TransactionBuilder = TransactionBuilder(notary = DUMMY_NOTARY),
@ -135,7 +135,7 @@ class LedgerDSL<out T : TransactionDSLInterpreter, out L : LedgerDSLInterpreter<
_transaction(label, transactionBuilder, dsl)
/**
* @see LedgerDSLInterpreter._unverifiedTransaction
* Creates and adds a transaction to the ledger that will not be verified by [verifies].
*/
@JvmOverloads
fun unverifiedTransaction(label: String? = null, transactionBuilder: TransactionBuilder = TransactionBuilder(notary = DUMMY_NOTARY),
@ -143,7 +143,7 @@ class LedgerDSL<out T : TransactionDSLInterpreter, out L : LedgerDSLInterpreter<
_unverifiedTransaction(label, transactionBuilder, dsl)
/**
* @see OutputStateLookup.retrieveOutputStateAndRef
* Retrieves an output previously defined by [TransactionDSLInterpreter._output] with a label passed in.
*/
inline fun <reified S : ContractState> String.outputStateAndRef(): StateAndRef<S> =
retrieveOutputStateAndRef(S::class.java, this)
@ -156,7 +156,7 @@ class LedgerDSL<out T : TransactionDSLInterpreter, out L : LedgerDSLInterpreter<
outputStateAndRef<S>().state.data
/**
* @see OutputStateLookup.retrieveOutputStateAndRef
* Retrieves an output previously defined by [TransactionDSLInterpreter._output] with a label passed in.
*/
fun <S : ContractState> retrieveOutput(clazz: Class<S>, label: String) =
retrieveOutputStateAndRef(clazz, label).state.data

15
testing/test-utils/src/main/kotlin/net/corda/testing/TransactionDSLInterpreter.kt
View File

@ -12,7 +12,7 @@ import java.time.Instant
/**
* This interface defines the bare bone functionality that a Transaction DSL interpreter should implement.
* @param <R> The return type of [verifies]/[failsWith] and the like. It is generic so that we have control over whether
* we want to enforce users to call these methods (@see [EnforceVerifyOrFail]) or not.
* we want to enforce users to call these methods (see [EnforceVerifyOrFail]) or not.
*/
interface TransactionDSLInterpreter : Verifies, OutputStateLookup {
/**
@ -33,7 +33,7 @@ interface TransactionDSLInterpreter : Verifies, OutputStateLookup {
* @param encumbrance The position of the encumbrance state.
* @param attachmentConstraint The attachment constraint
* @param contractState The state itself.
* @params contractClassName The class name of the contract that verifies this state.
* @param contractClassName The class name of the contract that verifies this state.
*/
fun _output(contractClassName: ContractClassName,
label: String?,
@ -96,7 +96,7 @@ class TransactionDSL<out T : TransactionDSLInterpreter>(val interpreter: T) : Tr
fun input(contractClassName: ContractClassName, stateClosure: () -> ContractState) = input(contractClassName, stateClosure())
/**
* @see TransactionDSLInterpreter._output
* Adds an output to the transaction.
*/
@JvmOverloads
fun output(contractClassName: ContractClassName,
@ -108,24 +108,27 @@ class TransactionDSL<out T : TransactionDSLInterpreter>(val interpreter: T) : Tr
_output(contractClassName, label, notary, encumbrance, attachmentConstraint, contractStateClosure())
/**
* @see TransactionDSLInterpreter._output
* Adds a labelled output to the transaction.
*/
@JvmOverloads
fun output(contractClassName: ContractClassName, label: String, contractState: ContractState, attachmentConstraint: AttachmentConstraint = AutomaticHashConstraint) =
_output(contractClassName, label, DUMMY_NOTARY, null, attachmentConstraint, contractState)
/**
* Adds an output to the transaction.
*/
@JvmOverloads
fun output(contractClassName: ContractClassName, contractState: ContractState, attachmentConstraint: AttachmentConstraint = AutomaticHashConstraint) =
_output(contractClassName,null, DUMMY_NOTARY, null, attachmentConstraint, contractState)
/**
* @see TransactionDSLInterpreter._command
* Adds a command to the transaction.
*/
fun command(vararg signers: PublicKey, commandDataClosure: () -> CommandData) =
_command(listOf(*signers), commandDataClosure())
/**
* @see TransactionDSLInterpreter._command
* Adds a command to the transaction.
*/
fun command(signer: PublicKey, commandData: CommandData) = _command(listOf(signer), commandData)