Fix javadoc for ethereum:core top level package (hyperledger#7270)

* javadoc - Apply javadoc to ethereum core top level package

---------

Signed-off-by: Usman Saleem <usman@usmans.info>
Signed-off-by: Daniel Lehrner <daniel.lehrner@consensys.net>

build.gradle

@@ -366,7 +366,6 @@ allprojects {
       '-org.hyperledger.besu.tests.acceptance.*,' +
       '-org.hyperledger.besu.tests.web3j.generated,' +
       // TODO: these are temporary disabled (ethereum and sub modules), it should be removed in a future PR.
-      '-org.hyperledger.besu.ethereum,' +
       '-org.hyperledger.besu.ethereum.*,' +
       '-org.hyperledger.besu.evmtool',
       true)

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockProcessingOutputs.java

@@ -21,17 +21,31 @@
 import java.util.List;
 import java.util.Optional;
 
+/** Contains the outputs of processing a block. */
 public class BlockProcessingOutputs {
 
   private final MutableWorldState worldState;
   private final List<TransactionReceipt> receipts;
   private final Optional<List<Request>> maybeRequests;
 
+  /**
+   * Creates a new instance.
+   *
+   * @param worldState the world state after processing the block
+   * @param receipts the receipts produced by processing the block
+   */
   public BlockProcessingOutputs(
       final MutableWorldState worldState, final List<TransactionReceipt> receipts) {
     this(worldState, receipts, Optional.empty());
   }
 
+  /**
+   * Creates a new instance.
+   *
+   * @param worldState the world state after processing the block
+   * @param receipts the receipts produced by processing the block
+   * @param maybeRequests the requests produced by processing the block
+   */
   public BlockProcessingOutputs(
       final MutableWorldState worldState,
       final List<TransactionReceipt> receipts,
@@ -41,14 +55,29 @@ public BlockProcessingOutputs(
     this.maybeRequests = maybeRequests;
   }
 
+  /**
+   * Returns the world state after processing the block.
+   *
+   * @return the world state after processing the block
+   */
   public MutableWorldState getWorldState() {
     return worldState;
   }
 
+  /**
+   * Returns the receipts produced by processing the block.
+   *
+   * @return the receipts produced by processing the block
+   */
   public List<TransactionReceipt> getReceipts() {
     return receipts;
   }
 
+  /**
+   * Returns the requests produced by processing the block.
+   *
+   * @return the requests produced by processing the block
+   */
   public Optional<List<Request>> getRequests() {
     return maybeRequests;
   }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockProcessingResult.java

@@ -20,38 +20,70 @@
 import java.util.List;
 import java.util.Optional;
 
+/** Contains the outputs of processing a block. */
 public class BlockProcessingResult extends BlockValidationResult {
 
   private final Optional<BlockProcessingOutputs> yield;
   private final boolean isPartial;
 
+  /** A result indicating that processing failed. */
   public static final BlockProcessingResult FAILED = new BlockProcessingResult("processing failed");
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   */
   public BlockProcessingResult(final Optional<BlockProcessingOutputs> yield) {
     this.yield = yield;
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param isPartial whether the processing was incomplete
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final boolean isPartial) {
     this.yield = yield;
     this.isPartial = isPartial;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param errorMessage the error message if any
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final String errorMessage) {
     super(errorMessage);
     this.yield = yield;
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param cause the cause of the error if any
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield, final Throwable cause) {
     super(cause.getLocalizedMessage(), cause);
     this.yield = yield;
     this.isPartial = false;
   }
 
+  /**
+   * A result indicating that processing was successful but incomplete.
+   *
+   * @param yield the outputs of processing a block
+   * @param errorMessage the error message if any
+   * @param isPartial whether the processing was incomplete
+   */
   public BlockProcessingResult(
       final Optional<BlockProcessingOutputs> yield,
       final String errorMessage,
@@ -61,20 +93,40 @@ public BlockProcessingResult(
     this.isPartial = isPartial;
   }
 
+  /**
+   * A result indicating that processing failed.
+   *
+   * @param errorMessage the error message
+   */
   public BlockProcessingResult(final String errorMessage) {
     super(errorMessage);
     this.isPartial = false;
     this.yield = Optional.empty();
   }
 
+  /**
+   * Gets the block processing outputs of the result.
+   *
+   * @return the block processing outputs of the result
+   */
   public Optional<BlockProcessingOutputs> getYield() {
     return yield;
   }
 
+  /**
+   * Checks if the processing was incomplete.
+   *
+   * @return true if the processing was incomplete, false otherwise
+   */
   public boolean isPartial() {
     return isPartial;
   }
 
+  /**
+   * Gets the transaction receipts of the result.
+   *
+   * @return the transaction receipts of the result
+   */
   public List<TransactionReceipt> getReceipts() {
     if (yield.isEmpty()) {
       return new ArrayList<>();

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockValidationResult.java

@@ -16,38 +16,78 @@
 
 import java.util.Optional;
 
+/**
+ * Represents the result of a block validation. This class holds the success status, error message,
+ * and cause of the validation.
+ */
 public class BlockValidationResult {
 
+  /** The error message of the failed validation, if any. */
   public final Optional<String> errorMessage;
+
+  /** The cause of the failed validation, if any. */
   public final Optional<Throwable> cause;
+
+  /**
+   * The success status of the validation. True if the validation was successful, false otherwise.
+   */
   public final boolean success;
 
+  /** Constructs a new BlockValidationResult indicating a successful validation. */
   public BlockValidationResult() {
     this.success = true;
     this.errorMessage = Optional.empty();
     this.cause = Optional.empty();
   }
 
+  /**
+   * Constructs a new BlockValidationResult indicating a failed validation with the given error
+   * message.
+   *
+   * @param errorMessage the error message of the failed validation
+   */
   public BlockValidationResult(final String errorMessage) {
     this.success = false;
     this.errorMessage = Optional.of(errorMessage);
     this.cause = Optional.empty();
   }
 
+  /**
+   * Constructs a new BlockValidationResult indicating a failed validation with the given error
+   * message and cause.
+   *
+   * @param errorMessage the error message of the failed validation
+   * @param cause the cause of the failed validation
+   */
   public BlockValidationResult(final String errorMessage, final Throwable cause) {
     this.success = false;
     this.errorMessage = Optional.of(errorMessage);
     this.cause = Optional.of(cause);
   }
 
+  /**
+   * Checks if the validation was successful.
+   *
+   * @return true if the validation was successful, false otherwise
+   */
   public boolean isSuccessful() {
     return this.success;
   }
 
+  /**
+   * Checks if the validation failed.
+   *
+   * @return true if the validation failed, false otherwise
+   */
   public boolean isFailed() {
     return !isSuccessful();
   }
 
+  /**
+   * Gets the cause of the failed validation.
+   *
+   * @return the cause of the failed validation
+   */
   public Optional<Throwable> causedBy() {
     return cause;
   }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/BlockValidator.java

@@ -22,21 +22,58 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * The BlockValidator interface defines the methods for validating and processing blocks in the
+ * Ethereum protocol.
+ */
 public interface BlockValidator {
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, and
+   * ommer validation mode.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
       final HeaderValidationMode headerValidationMode,
       final HeaderValidationMode ommerValidationMode);
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, ommer
+   * validation mode, and persistence flag.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @param shouldPersist flag indicating whether the block should be persisted
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
       final HeaderValidationMode headerValidationMode,
       final HeaderValidationMode ommerValidationMode,
       final boolean shouldPersist);
 
+  /**
+   * Validates and processes a block with the given context, block, header validation mode, ommer
+   * validation mode, persistence flag, and bad block recording flag.
+   *
+   * @param context the protocol context
+   * @param block the block to validate and process
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @param shouldPersist flag indicating whether the block should be persisted
+   * @param shouldRecordBadBlock flag indicating whether bad blocks should be recorded
+   * @return the result of the block processing
+   */
   BlockProcessingResult validateAndProcessBlock(
       final ProtocolContext context,
       final Block block,
@@ -45,6 +82,18 @@ BlockProcessingResult validateAndProcessBlock(
       final boolean shouldPersist,
       final boolean shouldRecordBadBlock);
 
+  /**
+   * Performs fast block validation with the given context, block, transaction receipts, requests,
+   * header validation mode, and ommer validation mode.
+   *
+   * @param context the protocol context
+   * @param block the block to validate
+   * @param receipts the transaction receipts
+   * @param requests the requests
+   * @param headerValidationMode the header validation mode
+   * @param ommerValidationMode the ommer validation mode
+   * @return true if the block is valid, false otherwise
+   */
   boolean fastBlockValidation(
       final ProtocolContext context,
       final Block block,

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/ConsensusContext.java

@@ -14,7 +14,19 @@
  */
 package org.hyperledger.besu.ethereum;
 
+/**
+ * The ConsensusContext interface defines a method for casting the consensus context to a specific
+ * class.
+ */
 @FunctionalInterface
 public interface ConsensusContext {
+
+  /**
+   * Casts the consensus context to the specified class.
+   *
+   * @param <C> the type of the class to cast the consensus context to
+   * @param klass the class to cast the consensus context to
+   * @return the consensus context cast to the specified class
+   */
   <C extends ConsensusContext> C as(final Class<C> klass);
 }

ethereum/core/src/main/java/org/hyperledger/besu/ethereum/ConsensusContextFactory.java

@@ -18,9 +18,19 @@
 import org.hyperledger.besu.ethereum.mainnet.ProtocolSchedule;
 import org.hyperledger.besu.ethereum.worldstate.WorldStateArchive;
 
+/** The ConsensusContextFactory interface defines a method for creating a consensus context. */
 @FunctionalInterface
 public interface ConsensusContextFactory {
 
+  /**
+   * Creates a consensus context with the given blockchain, world state archive, and protocol
+   * schedule.
+   *
+   * @param blockchain the blockchain
+   * @param worldStateArchive the world state archive
+   * @param protocolSchedule the protocol schedule
+   * @return the created consensus context
+   */
   ConsensusContext create(
       Blockchain blockchain,
       WorldStateArchive worldStateArchive,