From fd07a26510b3cba0646f0c5d8bc34220e908c17f Mon Sep 17 00:00:00 2001 From: Stephen Compall Date: Tue, 28 Jul 2020 16:32:30 -0400 Subject: [PATCH] check for scaladoc comments that are not actually used (#6802) * add -Xlint:doc-detached - reverts 1feae964e369a010d8d4c69a9c522908e3c5354f from #6798 * attach several scaladocs where they'll actually be included * no changelog * attach several more scaladocs where they'll actually be included * no changelog CHANGELOG_BEGIN CHANGELOG_END --- bazel_tools/scala.bzl | 1 + .../daml/lf/ledger/EnrichedTransaction.scala | 5 ++- .../daml/lf/transaction/BlindingInfo.scala | 14 +++--- .../daml/lf/transaction/Node.scala | 11 ++--- .../codegen/lf/DamlDataTypeGen.scala | 44 ++++++++----------- .../configuration/LedgerConfiguration.scala | 29 ++++++------ .../configuration/PartyConfiguration.scala | 20 ++++----- .../main/scala/platform/store/Contract.scala | 1 - .../state/kvutils/InputsAndEffects.scala | 30 +++++++------ .../participant/state/v1/Configuration.scala | 7 +-- .../navigator/console/State.scala | 21 +++++---- .../digitalasset/navigator/model/Model.scala | 8 +++- 12 files changed, 99 insertions(+), 92 deletions(-) diff --git a/bazel_tools/scala.bzl b/bazel_tools/scala.bzl index c870e76675..94a62b29ad 100644 --- a/bazel_tools/scala.bzl +++ b/bazel_tools/scala.bzl @@ -53,6 +53,7 @@ common_scalacopts = [ "-Xlint:missing-interpolator", "-Xlint:by-name-right-associative", # will never be by-name if used correctly "-Xlint:constant", # / 0 + "-Xlint:doc-detached", # floating Scaladoc comment "-Xlint:inaccessible", # method uses invisible types "-Xlint:infer-any", # less thorough but less buggy version of the Any wart "-Xlint:option-implicit", # implicit conversion arg might be null diff --git a/daml-lf/interpreter/src/main/scala/com/digitalasset/daml/lf/ledger/EnrichedTransaction.scala b/daml-lf/interpreter/src/main/scala/com/digitalasset/daml/lf/ledger/EnrichedTransaction.scala index c854c07331..5cc5a4cfee 100644 --- a/daml-lf/interpreter/src/main/scala/com/digitalasset/daml/lf/ledger/EnrichedTransaction.scala +++ b/daml-lf/interpreter/src/main/scala/com/digitalasset/daml/lf/ledger/EnrichedTransaction.scala @@ -55,12 +55,15 @@ object EnrichedTransaction { else copy(failedAuthorizations = failedAuthorizations + (nodeId -> failWith)) + /** + * + * @param mbMaintainers If the create has a key, these are the maintainers + */ def authorizeCreate( nodeId: NodeId, create: NodeCreate.WithTxValue[ContractId], signatories: Set[Party], authorization: Authorization, - /** If the create has a key, these are the maintainers */ mbMaintainers: Option[Set[Party]], ): EnrichState = authorization.fold(this)( diff --git a/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/BlindingInfo.scala b/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/BlindingInfo.scala index 9ed6e5a087..1742dd3741 100644 --- a/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/BlindingInfo.scala +++ b/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/BlindingInfo.scala @@ -18,15 +18,15 @@ import com.daml.lf.value.Value.ContractId * contract ids -- e.g. contract ids that were created * _outside_ this transaction. * See also https://docs.daml.com/concepts/ledger-model/ledger-privacy.html#divulgence-when-non-stakeholders-see-contracts + * + * @param disclosure Disclosure, specified in terms of local node IDs + * @param divulgence + * Divulgence, specified in terms of contract IDs. + * Note that if this info was produced by blinding a transaction + * containing only contract ids, this map may also + * contain contracts produced in the same transaction. */ final case class BlindingInfo( - /** Disclosure, specified in terms of local node IDs */ disclosure: Relation[NodeId, Party], - /** - * Divulgence, specified in terms of contract IDs. - * Note that if this info was produced by blinding a transaction - * containing only contract ids, this map may also - * contain contracts produced in the same transaction. - */ divulgence: Relation[ContractId, Party], ) diff --git a/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/Node.scala b/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/Node.scala index c42729e24b..4875054329 100644 --- a/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/Node.scala +++ b/daml-lf/transaction/src/main/scala/com/digitalasset/daml/lf/transaction/Node.scala @@ -219,6 +219,12 @@ object Node { * We remember the `children` of this `NodeExercises` * to allow segregating the graph afterwards into party-specific * ledgers. + * + * @param controllersDifferFromActors + * When we decode transactions version<6, the controllers might be different + * from the actors. However, such a transaction is always invalid, so we + * prevalidate that when decoding and report the error when we get to the + * actual validation stage. */ final case class NodeExercises[+Nid, +Cid, +Val]( targetCoid: Cid, @@ -230,11 +236,6 @@ object Node { chosenValue: Val, stakeholders: Set[Party], signatories: Set[Party], - /** When we decode transactions version<6, the controllers might be different - * from the actors. However, such a transaction is always invalid, so we - * prevalidate that when decoding and report the error when we get to the - * actual validation stage. - */ controllersDifferFromActors: Boolean, children: ImmArray[Nid], exerciseResult: Option[Val], diff --git a/language-support/scala/codegen/src/main/scala/com/digitalasset/codegen/lf/DamlDataTypeGen.scala b/language-support/scala/codegen/src/main/scala/com/digitalasset/codegen/lf/DamlDataTypeGen.scala index ec87e6ad6c..3a07410828 100644 --- a/language-support/scala/codegen/src/main/scala/com/digitalasset/codegen/lf/DamlDataTypeGen.scala +++ b/language-support/scala/codegen/src/main/scala/com/digitalasset/codegen/lf/DamlDataTypeGen.scala @@ -95,10 +95,8 @@ object DamlDataTypeGen { ` mkDataTypeId`($packageIdRef, ${moduleName.dottedName}, ${baseName.dottedName}) """) - /** - * These implicit values are used as "evidence" in the ArgumentValueFormat - * type class instances of polymorphic types. - */ + // These implicit values are used as "evidence" in the ArgumentValueFormat + // type class instances of polymorphic types. val typeParamEvidences: List[Tree] = typeVars .filter(typeVarsInUse.contains) .zipWithIndex @@ -135,13 +133,11 @@ object DamlDataTypeGen { $valueInstanceExpr""" } - /** - * The generated class for a DAML enum type contains: - * - the definition of a "Value" trait - * - the definition of a _case object_ for each constructor of the DAML enum - * - A type class instance (i.e. implicit object) for serializing/deserializing - * to/from the ArgumentValue type (see typed-ledger-api project) - */ + // The generated class for a DAML enum type contains: + // - the definition of a "Value" trait + // - the definition of a _case object_ for each constructor of the DAML enum + // - A type class instance (i.e. implicit object) for serializing/deserializing + // to/from the ArgumentValue type (see typed-ledger-api project) def toScalaDamlEnumType(constructors: List[Ref.Name]): (Set[Tree], (Tree, Tree)) = { val className = damlScalaName.name.capitalize @@ -180,15 +176,13 @@ object DamlDataTypeGen { } - /** - * The generated class for a DAML variant type contains: - * - the definition of a "Value" trait - * - the definition of a _case class_ for each variant constructor of the DAML variant - * - "smart constructors" that create values for each constructor automatically up-casting - * to the Value (trait) type - * - A type class instance (i.e. implicit object) for serializing/deserializing - * to/from the ArgumentValue type (see typed-ledger-api project) - */ + // The generated class for a DAML variant type contains: + // - the definition of a "Value" trait + // - the definition of a _case class_ for each variant constructor of the DAML variant + // - "smart constructors" that create values for each constructor automatically up-casting + // to the Value (trait) type + // - A type class instance (i.e. implicit object) for serializing/deserializing + // to/from the ArgumentValue type (see typed-ledger-api project) def toScalaDamlVariantType(fields: List[(Ref.Name, VariantField)]): (Tree, Tree) = { lazy val damlVariant = if (fields.isEmpty) damlVariantZeroFields @@ -327,12 +321,10 @@ object DamlDataTypeGen { damlVariant } - /** - * The generated class for a DAML record type contains: - * - the definition of a "Value" case class that contains all the DAML record fields/types. - * - An type class instance (i.e. implicit object) for serializing/deserializing - * to/from the ArgumentValue type (see typed-ledger-api project) - */ + // The generated class for a DAML record type contains: + // - the definition of a "Value" case class that contains all the DAML record fields/types. + // - An type class instance (i.e. implicit object) for serializing/deserializing + // to/from the ArgumentValue type (see typed-ledger-api project) def toScalaDamlRecordType(fields: Seq[FieldWithType]): (Tree, Tree) = { lazy val damlRecord = { diff --git a/ledger/participant-integration-api/src/main/scala/platform/configuration/LedgerConfiguration.scala b/ledger/participant-integration-api/src/main/scala/platform/configuration/LedgerConfiguration.scala index b576d59b24..e54ebe241d 100644 --- a/ledger/participant-integration-api/src/main/scala/platform/configuration/LedgerConfiguration.scala +++ b/ledger/participant-integration-api/src/main/scala/platform/configuration/LedgerConfiguration.scala @@ -7,26 +7,23 @@ import java.time.Duration import com.daml.ledger.participant.state.v1.{Configuration, TimeModel} -/** - * Configuration surrounding ledger parameters. +/** Configuration surrounding ledger parameters. + * + * @param initialConfiguration + * The initial ledger configuration to submit if the ledger does not contain one yet. + * @param initialConfigurationSubmitDelay + * The delay until the ledger API server tries to submit an initial configuration at startup if none exists. + * @param configurationLoadTimeout + * The amount of time the ledger API server will wait to load a ledger configuration. + * + * The ledger API server waits at startup until it reads at least one configuration changed update from the ledger. + * If none is found within this timeout, the ledger API server will start anyway, but services that depend + * on the ledger configuration (e.g., SubmissionService or CommandService) will reject all requests with the + * UNAVAILABLE error. */ case class LedgerConfiguration( - /** - * The initial ledger configuration to submit if the ledger does not contain one yet. - */ initialConfiguration: Configuration, - /** - * The delay until the ledger API server tries to submit an initial configuration at startup if none exists. - */ initialConfigurationSubmitDelay: Duration, - /** - * The amount of time the ledger API server will wait to load a ledger configuration. - * - * The ledger API server waits at startup until it reads at least one configuration changed update from the ledger. - * If none is found within this timeout, the ledger API server will start anyway, but services that depend - * on the ledger configuration (e.g., SubmissionService or CommandService) will reject all requests with the - * UNAVAILABLE error. - */ configurationLoadTimeout: Duration, ) diff --git a/ledger/participant-integration-api/src/main/scala/platform/configuration/PartyConfiguration.scala b/ledger/participant-integration-api/src/main/scala/platform/configuration/PartyConfiguration.scala index 2e29d26294..842dd41872 100644 --- a/ledger/participant-integration-api/src/main/scala/platform/configuration/PartyConfiguration.scala +++ b/ledger/participant-integration-api/src/main/scala/platform/configuration/PartyConfiguration.scala @@ -5,18 +5,18 @@ package com.daml.platform.configuration /** * Configuration surrounding parties and party allocation. + * + * @param implicitPartyAllocation + * Informs the Command Submission Service that any parties mentioned in a submission that do + * not already exist should be created on the fly. This behavior will not make sense for most + * ledgers, because: + * - allocating parties can be racy if multiple transactions are coming through at once, + * - if allocation fails, the errors are a little confusing, and + * - parties can be allocated without administrator privileges. + * + * Enable at your own risk. */ case class PartyConfiguration( - /** - * Informs the Command Submission Service that any parties mentioned in a submission that do - * not already exist should be created on the fly. This behavior will not make sense for most - * ledgers, because: - * - allocating parties can be racy if multiple transactions are coming through at once, - * - if allocation fails, the errors are a little confusing, and - * - parties can be allocated without administrator privileges. - * - * Enable at your own risk. - */ implicitPartyAllocation: Boolean, ) diff --git a/ledger/participant-integration-api/src/main/scala/platform/store/Contract.scala b/ledger/participant-integration-api/src/main/scala/platform/store/Contract.scala index 344dd8e9b0..2d1d5757bc 100644 --- a/ledger/participant-integration-api/src/main/scala/platform/store/Contract.scala +++ b/ledger/participant-integration-api/src/main/scala/platform/store/Contract.scala @@ -42,7 +42,6 @@ private[platform] object Contract { final case class DivulgedContract( id: Value.ContractId, contract: ContractInst[VersionedValue[ContractId]], - /** For each party, the transaction id at which the contract was divulged */ divulgences: Map[Party, TransactionId], ) extends Contract diff --git a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/InputsAndEffects.scala b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/InputsAndEffects.scala index 6bffe782ca..b1546db11a 100644 --- a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/InputsAndEffects.scala +++ b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/InputsAndEffects.scala @@ -17,23 +17,27 @@ private[kvutils] object InputsAndEffects { /** The effects of the transaction, that is what contracts * were consumed and created, and what contract keys were updated. */ + /** + * + * @param consumedContracts + * The contracts consumed by this transaction. + * When committing the transaction these contracts must be marked consumed. + * A contract should be marked consumed when the transaction is committed, + * regardless of the ledger effective time of the transaction (e.g. a transaction + * with an earlier ledger effective time that gets committed later would find the + * contract inactive). + * @param createdContracts + * The contracts created by this transaction. + * When the transaction is committed, keys marking the activeness of these + * contracts should be created. The key should be a combination of the transaction + * id and the relative contract id (that is, the node index). + * @param updatedContractKeys + * The contract keys created or updated as part of the transaction. + */ final case class Effects( - /** The contracts consumed by this transaction. - * When committing the transaction these contracts must be marked consumed. - * A contract should be marked consumed when the transaction is committed, - * regardless of the ledger effective time of the transaction (e.g. a transaction - * with an earlier ledger effective time that gets committed later would find the - * contract inactive). - */ consumedContracts: List[DamlStateKey], - /** The contracts created by this transaction. - * When the transaction is committed, keys marking the activeness of these - * contracts should be created. The key should be a combination of the transaction - * id and the relative contract id (that is, the node index). - */ createdContracts: List[ (DamlStateKey, Node.NodeCreate[ContractId, VersionedValue[ContractId]])], - /** The contract keys created or updated as part of the transaction. */ updatedContractKeys: Map[DamlStateKey, Option[ContractId]] ) object Effects { diff --git a/ledger/participant-state/src/main/scala/com/daml/ledger/participant/state/v1/Configuration.scala b/ledger/participant-state/src/main/scala/com/daml/ledger/participant/state/v1/Configuration.scala index 8d11e04d6f..b235c25a0c 100644 --- a/ledger/participant-state/src/main/scala/com/daml/ledger/participant/state/v1/Configuration.scala +++ b/ledger/participant-state/src/main/scala/com/daml/ledger/participant/state/v1/Configuration.scala @@ -9,13 +9,14 @@ import scala.util.Try /** Ledger configuration describing the ledger's time model. * Emitted in [[com.daml.ledger.participant.state.v1.Update.ConfigurationChanged]]. + * + * @param generation The configuration generation. Monotonically increasing. + * @param timeModel The time model of the ledger. Specifying the time-to-live bounds for Ledger API commands. + * @param maxDeduplicationTime The maximum time window during which commands can be deduplicated. */ final case class Configuration( - /* The configuration generation. Monotonically increasing. */ generation: Long, - /** The time model of the ledger. Specifying the time-to-live bounds for Ledger API commands. */ timeModel: TimeModel, - /** The maximum time window during which commands can be deduplicated. */ maxDeduplicationTime: Duration, ) diff --git a/navigator/backend/src/main/scala/com/digitalasset/navigator/console/State.scala b/navigator/backend/src/main/scala/com/digitalasset/navigator/console/State.scala index dc0ac704c9..0a5954b35e 100644 --- a/navigator/backend/src/main/scala/com/digitalasset/navigator/console/State.scala +++ b/navigator/backend/src/main/scala/com/digitalasset/navigator/console/State.scala @@ -13,27 +13,30 @@ import org.jline.terminal.Terminal import scala.concurrent.ExecutionContext +/** + * + * @param quit Set to true to request an application shutdown + * @param rebuildLineReader Set to true to request a rebuild of the LineReader (updates help text and tab completion) + * @param party Current party + * @param arguments CLI arguments used to start this application + * @param config Contains per-party state (including contract store) + * @param store Main actor for the interaction with the ledger API + * @param ec Execution context of the console + * @param graphQL Handles GraphQL queries + * @param applicationInfo Application name and version + */ final case class State( terminal: Terminal, reader: LineReader, history: History, - /** Set to true to request an application shutdown */ quit: Boolean, - /** Set to true to request a rebuild of the LineReader (updates help text and tab completion) */ rebuildLineReader: Boolean, - /** Current party */ party: ApiTypes.Party, - /** CLI arguments used to start this application */ arguments: Arguments, - /** Contains per-party state (including contract store) */ config: Config, - /** Main actor for the interaction with the ledger API */ store: ActorRef, - /** Execution context of the console */ ec: ExecutionContext, - /** Handles GraphQL queries */ graphQL: GraphQLHandler, - /** Application name and version */ applicationInfo: ApplicationInfo ) { def getPartyState: Option[PartyState] = config.parties.find(p => p.name == party) diff --git a/navigator/backend/src/main/scala/com/digitalasset/navigator/model/Model.scala b/navigator/backend/src/main/scala/com/digitalasset/navigator/model/Model.scala index 1910c2c52e..4c728beeee 100644 --- a/navigator/backend/src/main/scala/com/digitalasset/navigator/model/Model.scala +++ b/navigator/backend/src/main/scala/com/digitalasset/navigator/model/Model.scala @@ -75,13 +75,19 @@ final case class CreateCommand( argument: ApiRecord ) extends Command +/** + * + * @param template + * The template of the given contract. Not required for the ledger API, but we keep + * this denormalized information so that it's easier to serialize/deserialize the + * choice argument. + */ final case class ExerciseCommand( id: ApiTypes.CommandId, index: Long, workflowId: ApiTypes.WorkflowId, platformTime: Instant, contract: ApiTypes.ContractId, - /** The template of the given contract. Not required for the ledger API, but we keep this denormalized information so that it's easier to serialize/deserialize the choice argument. */ template: DamlLfIdentifier, choice: ApiTypes.Choice, argument: ApiValue