JavaDoc warning fixes, prep for 0.8.0

mikera · mikera · commit d4b8dc261ee2 · 2025-02-16T16:13:50.000Z
diff --git a/convex-cli/src/main/java/convex/cli/mixins/RemotePeerMixin.java b/convex-cli/src/main/java/convex/cli/mixins/RemotePeerMixin.java
@@ -56,7 +56,7 @@ public InetSocketAddress getSocketAddress() {
 
 	/**
 	 * Gets the socket address for the remote peer, or null if not specified in CLI
-	 * @return
+	 * @return Socket address instance, or null if not specified at CLI
 	 */
 	public InetSocketAddress getSpecifiedSource() {
 		if (hostname==null) return null;
diff --git a/convex-core/src/main/java/convex/core/Result.java b/convex-core/src/main/java/convex/core/Result.java
@@ -73,7 +73,7 @@ private Result(AVector<ACell> values) {
 	/**
 	 * Build a Result from a vector. WARNING: does not validate values
 	 * @param values
-	 * @return
+	 * @return Result instance
 	 */
 	public static Result buildFromVector(AVector<ACell> values) {
 		return new Result(values);
diff --git a/convex-core/src/main/java/convex/core/cpos/Belief.java b/convex-core/src/main/java/convex/core/cpos/Belief.java
@@ -90,8 +90,8 @@ public static Belief create(AKeyPair kp, Order order) {
 	
 	/**
 	 * Creates a Belief from source data , usually an Index of Peer key -> Signed Orders
-	 * @param source
-	 * @return
+	 * @param source Map containing Orders
+	 * @return Belief constructed from given Order(s), or null if not valid
 	 */
 	@SuppressWarnings("unchecked")
 	public static Belief fromOrders(ACell source) {
@@ -244,7 +244,7 @@ public void validateStructure() throws InvalidDataException {
 	/**
 	 * Propose a new Block at the end of the current Order
 	 * @param kp Keypair with which to sign Order
-	 * @param signedBlock Signed Block of transactions
+	 * @param signedBlocks Signed Blocks of transactions
 	 * @return Updated Belief with new Order
 	 */
 	@SuppressWarnings("unchecked")
diff --git a/convex-core/src/main/java/convex/core/crypto/AKeyPair.java b/convex-core/src/main/java/convex/core/crypto/AKeyPair.java
@@ -316,7 +316,7 @@ public static PublicKey publicKeyFromBytes(byte[] key) throws BadFormatException
 	/**
 	 * Create a key pair from a hex string seed. Strips whitespace and leading 0x if needed.
 	 * @param seed Hex string containing 32 byte Ed25519 seed
-	 * @return
+	 * @return Key pair instance
 	 */
 	public static AKeyPair create(String seed) {
 		Blob b=Blob.parse(seed);
diff --git a/convex-core/src/main/java/convex/core/crypto/BIP39.java b/convex-core/src/main/java/convex/core/crypto/BIP39.java
@@ -367,7 +367,7 @@ public static List<String> createWordsAddingChecksum(byte[] entropy, int n) {
 	
 	/**
 	 * Check if BIP39 checksum is correct
-	 * @param s
+	 * @param mnemonic BIP39 mnemonic words
 	 * @return True if BIP39 checksum is valid
 	 */
 	public static boolean checkSum(String mnemonic) {
@@ -408,7 +408,7 @@ public static byte[] mnemonicToBytes(String mnemonic) {
 	
 	/**
 	 * Gets bytes containing the entropy and checksum used to create the given words
-	 * @param mnemonic
+	 * @param words List of BIP39 words (should be valid BIP39)
 	 * @return byte array of sufficient size, or null if not valid BIP39 words
 	 */
 	public static byte[] mnemonicToBytes(List<String> words) {
@@ -510,7 +510,7 @@ public static String checkWords(List<String> words) {
 	/**
 	 * Extends an abbreviated form of a BIP39 word to a full word e.g. 'SHAL' => 'shallow'
 	 * @param abbr
-	 * @return
+	 * @return Full lowercase PIB39 word
 	 */
 	public static String extendWord(String abbr) {
 		return ABBR.get(abbr.trim().toLowerCase());
diff --git a/convex-core/src/main/java/convex/core/cvm/Context.java b/convex-core/src/main/java/convex/core/cvm/Context.java
@@ -2382,7 +2382,7 @@ public AccountKey getPeer() {
 
 	/**
 	 * Gets the most recent log entry, or null if not available.
-	 * @return
+	 * @return Last log entry, or null if no log entries present
 	 */
 	public AVector<ACell> lastLog() {
 		AVector<AVector<ACell>> log=getLog();
diff --git a/convex-core/src/main/java/convex/core/cvm/Ops.java b/convex-core/src/main/java/convex/core/cvm/Ops.java
@@ -66,8 +66,8 @@ public static <T extends ACell> AOp<T> ensureOp(ACell a) {
 
 	/**
 	 * Cast any value to an Op. Returns value as a Constant op if not already an Op
-	 * @param aOp
-	 * @return
+	 * @param a Cell to cast to an Op (null results in a Constant nil op)
+	 * @return Op instance
 	 */
 	@SuppressWarnings("unchecked")
 	public static <T extends ACell> AOp<T> castOp(ACell a) {
diff --git a/convex-core/src/main/java/convex/core/cvm/Peer.java b/convex-core/src/main/java/convex/core/cvm/Peer.java
@@ -741,7 +741,7 @@ public boolean isReadyToPublish() {
 
 	/**
 	 * Gets the genesis state hash for this peer
-	 * @return
+	 * @return Hash of genesis state
 	 */
 	public Hash getGenesisHash() {
 		return getGenesisState().getHash();
diff --git a/convex-core/src/main/java/convex/core/cvm/State.java b/convex-core/src/main/java/convex/core/cvm/State.java
@@ -202,7 +202,6 @@ public State withBalance(Address address, long newBalance) {
 	 * 
 	 * @param signedBlock Signed Block to apply
 	 * @return The BlockResult from applying the given Block to this State
-	 * @throws InvalidBlockException 
 	 */
 	public BlockResult applyBlock(SignedData<Block> signedBlock) {
 		Block block=null;
@@ -510,7 +509,7 @@ public ResultContext applyTransaction(SignedData<ATransaction> t2, TransactionCo
 	 *
 	 * There are three phases in application of a transaction:
 	 * <ol>
-	 * <li>Preparation for accounting, with {@link #prepareTransaction(ResultContext) prepareTransaction}</li>
+	 * <li>Preparation for accounting, with {@link #prepareTransaction(ResultContext,TransactionContext) prepareTransaction}</li>
 	 * <li>Functional application of the transaction with ATransaction.apply(....)</li>
 	 * <li>Completion of accounting, with completeTransaction</li>
 	 * </ol>
@@ -552,7 +551,7 @@ public ResultContext applyTransaction(ATransaction t, TransactionContext tctx) {
 	/**
 	 * Apply a transaction in a detached transaction context, mainly for test / query
 	 * @param t Transaction
-	 * @return
+	 * @return ResultContext after transaction is applied
 	 */
 	public ResultContext applyTransaction(ATransaction t) {
 		return applyTransaction(t,TransactionContext.create(this));
diff --git a/convex-core/src/main/java/convex/core/cvm/ops/Invoke.java b/convex-core/src/main/java/convex/core/cvm/ops/Invoke.java
@@ -45,7 +45,7 @@ public static <T extends ACell> Invoke<T> create(AOp<?>... ops) {
 	 *  Build an invoke using the given values. Slow, for testing purposes
 	 * @param <T>
 	 * @param vals
-	 * @return
+	 * @return Invoke transaction instance
 	 */
 	public static <T extends ACell> Invoke<T> build(Object... vals) {
 		int n=vals.length;
diff --git a/convex-core/src/main/java/convex/core/data/AEncoder.java b/convex-core/src/main/java/convex/core/data/AEncoder.java
@@ -15,7 +15,7 @@ public abstract class AEncoder<T> {
 	/**
 	 * Encodes a value as Blob
 	 * @param a
-	 * @return
+	 * @return Blob encoding in CAD3 format
 	 */
 	public abstract Blob encode(T a);
 	
@@ -27,7 +27,7 @@ public T decode(Blob encoding) throws BadFormatException {
 
 	/**
 	 * Reads a value from a Blob of data
-	 * @param data Data to decode
+	 * @param enc Data to decode
 	 * @return Value instance
 	 * @throws BadFormatException If encoding format is invalid
 	 */
diff --git a/convex-core/src/main/java/convex/core/data/ASequence.java b/convex-core/src/main/java/convex/core/data/ASequence.java
@@ -204,8 +204,8 @@ public ASequence<T> assoc(ACell key, ACell value) {
 	/**
 	 * Checks if an index range is valid for this sequence
 	 * 
-	 * @param start
-	 * @param length
+	 * @param start Start index (Inclusive)
+	 * @param end End index (exclusive)
 	 */
 	protected boolean checkRange(long start, long end) {
 		if (start < 0) return false;
diff --git a/convex-core/src/main/java/convex/core/data/CAD3Encoder.java b/convex-core/src/main/java/convex/core/data/CAD3Encoder.java
@@ -159,7 +159,7 @@ protected ACell readExtension(byte tag, Blob blob, int offset) throws BadFormatE
 
 	/**
 	 * Reads a cell value from a Blob of data, allowing for non-embedded branches following the first cell
-	 * @param data Data to decode
+	 * @param enc Data to decode
 	 * @return Cell instance
 	 * @throws BadFormatException If CAD3 encoding format is invalid
 	 */
diff --git a/convex-core/src/main/java/convex/core/data/Cells.java b/convex-core/src/main/java/convex/core/data/Cells.java
@@ -86,7 +86,7 @@ public static boolean equalsGeneric(ACell a, ACell b) {
 	/**
 	 * Converts any collection object to an ACell[] array. Elements must be Cells.
 	 *
-	 * @param anyArray Array to convert
+	 * @param any Object representing an array to convert
 	 * @return ACell[] array
 	 */
 	@SuppressWarnings("unchecked")
@@ -134,7 +134,7 @@ public static int refCount(ACell a) {
 	 * Gets the number of Branches directly contained in a Cell (will be zero if the
 	 * Cell is not a Ref container)
 	 *
-	 * @param a Cell to check (may be null)
+	 * @param v Cell to check (may be null)
 	 * @return Number of Refs in the object.
 	 */
 	public static int branchCount(ACell v) {
diff --git a/convex-core/src/main/java/convex/core/data/Format.java b/convex-core/src/main/java/convex/core/data/Format.java
@@ -1017,9 +1017,9 @@ private static Blob encodeMultiCell(ACell topCell, ArrayList<Ref<?>> branches, b
 	}
 	
 	/**
-	 * Encode a Vector of cells down to the encodings of each vector element
-	 * @param v
-	 * @return
+	 * Encode a Result down to the encodings of each vector element
+	 * @param result Result containing a Vector value
+	 * @return Multi-cell encoding of Result
 	 */
 	public static Blob encodeDataResult(Result result) {
 		AVector<?> v=RT.ensureVector(result.getValue());
diff --git a/convex-core/src/main/java/convex/core/data/SetTree.java b/convex-core/src/main/java/convex/core/data/SetTree.java
@@ -71,7 +71,6 @@ private static <T extends ACell> long computeCount(Ref<AHashSet<T>>[] children)
 	 * 
 	 * @param <V> Type of elements
 	 * @param elementRefs Array of Refs to elements
-	 * @param shift Hex digit position at which to split children.
 	 * @return New SetTree node
 	 */
 	@SuppressWarnings("unchecked")
diff --git a/convex-core/src/main/java/convex/core/data/Strings.java b/convex-core/src/main/java/convex/core/data/Strings.java
@@ -125,8 +125,8 @@ public static AString create(String s) {
 	
 	/**
 	 * Create a canonical CVM String from an object
-	 * @param s Java String to convert.
-	 * @return CVM String instance, or null if input was null
+	 * @param o Java Object to convert.
+	 * @return CVM String instance, or "nil" if input was null
 	 */
 	public static AString create(Object o) {
 		if (o==null) return NIL;
diff --git a/convex-core/src/main/java/convex/core/data/VectorLeaf.java b/convex-core/src/main/java/convex/core/data/VectorLeaf.java
@@ -440,7 +440,7 @@ public void add(T e) {
 
 	/**
 	 * Get the length of the prefix vector, will be 0 if no prefix
-	 * @return
+	 * @return Length of prefix, in number of elements
 	 */
 	public long prefixLength() {
 		return count - items.length;
diff --git a/convex-core/src/main/java/convex/core/data/Vectors.java b/convex-core/src/main/java/convex/core/data/Vectors.java
@@ -173,8 +173,9 @@ public static <T extends ACell> AVector<T> read(Blob b, int pos) throws BadForma
 
 	/**
 	 * Create a Vector which represents a range of integers from start to end
-	 * @param count
-	 * @return
+	 * @param start Start index (inclusive)
+	 * @param end End index (exclusive)
+	 * @return Vector containing Integer range specified
 	 */
 	public static AVector<CVMLong> range(long start, long end) {
 		throw new TODOException();
diff --git a/convex-core/src/main/java/convex/core/data/prim/ByteFlag.java b/convex-core/src/main/java/convex/core/data/prim/ByteFlag.java
@@ -33,8 +33,8 @@ public ByteFlag(byte tag) {
 
 	/**
 	 * Creates an extended byte flag for the given value 0-15
-	 * @param value
-	 * @return
+	 * @param value Value to include in byte flag (0-15), only low bits used
+	 * @return Byteflag with given value
 	 */
 	public static ByteFlag create(long value) {
 		int m=(int)(value&0xf);
diff --git a/convex-core/src/main/java/convex/core/init/Init.java b/convex-core/src/main/java/convex/core/init/Init.java
@@ -388,7 +388,7 @@ private static State addStandardLibraries(State s) {
 	/**
 	 * Add extra libraries for testing purposes, not part of official genesis
 	 * @param peerKeys
-	 * @return
+	 * @return Test State instance
 	 */
 	public static State createTestState(List<AccountKey> peerKeys) {
 		State s=createState(peerKeys);
diff --git a/convex-core/src/main/java/convex/core/lang/Compiler.java b/convex-core/src/main/java/convex/core/lang/Compiler.java
@@ -100,7 +100,7 @@ public static Context expandCompile(ACell form, Context context) {
 	 * 
 	 * Updates context with result, juice consumed
 	 * 
-	 * @param expandedForm A fully expanded form expressed as a Syntax Object
+	 * @param form A fully expanded form expressed as a Syntax Object
 	 * @param context
 	 * @return Context with compiled Op as result
 	 */
diff --git a/convex-core/src/main/java/convex/core/lang/Core.java b/convex-core/src/main/java/convex/core/lang/Core.java
@@ -3014,8 +3014,7 @@ private static Context applyDocumentation(Context ctx) throws IOException {
  	
  	/**
  	 * Read a Core definition from an encoding
- 	 * @param b Blob containing encoding
- 	 * @param pos Position to read Core code function
+ 	 * @param code Code ID index
  	 * @return Singleton cell representing the Core value, or null if not defined
  	 */
 	public static ACell fromCode(long code) throws BadFormatException {
diff --git a/convex-core/src/main/java/convex/core/lang/RT.java b/convex-core/src/main/java/convex/core/lang/RT.java
@@ -721,7 +721,7 @@ public static <T extends ACell> AVector<T> vec(Object o) {
 	 * 
 	 * @param o Object to attempt to convert to a Vector. 
 	 * @param start start index to slice
-	 * @end end index to slice
+	 * @param end index to slice
 	 * @return AVector instance, or null if not convertible
 	 */
 	@SuppressWarnings("unchecked")
@@ -1445,7 +1445,7 @@ public static Keyword castKeyword(ACell a) {
 	/**
 	 * Casts to a Keyword
 	 * @param a
-	 * @return
+	 * @return Keyword instance, or null if cast fails
 	 */
 	public static Keyword ensureKeyword(ACell a) {
 		if (a instanceof Keyword)
diff --git a/convex-core/src/main/java/convex/core/lattice/ALattice.java b/convex-core/src/main/java/convex/core/lattice/ALattice.java
@@ -11,7 +11,7 @@ public abstract class ALattice {
 	 * Implementation of merge function
 	 * @param ownValue Own lattice value
 	 * @param otherValue Externally received lattice value
-	 * @return
+	 * @return Merged lattice root cell
 	 */
 	public abstract ACell merge(ACell ownValue, ACell otherValue);
 }
diff --git a/convex-core/src/main/java/convex/core/message/Message.java b/convex-core/src/main/java/convex/core/message/Message.java
@@ -1,6 +1,5 @@
 package convex.core.message;
 
-import java.io.IOException;
 import java.util.function.Predicate;
 
 import org.slf4j.Logger;
@@ -154,7 +153,7 @@ public Blob getMessageData() {
 
 	/**
 	 * Get the type of this message. May be UNKOWN if the message cannot be understood / processed
-	 * @return
+	 * @return Type of message
 	 */
 	public MessageType getType() {
 		if (type==null) type=inferType();
@@ -244,7 +243,7 @@ public ACell getID()  {
 	
 	/**
 	 * Gets the request ID for this message, assuming it is a request expecting a response
-	 * @return
+	 * @return ID of message (usually an Integer) or null if no ID present
 	 */
 	public ACell getRequestID() {
 		// if (payload==null) throw new IllegalStateException("Attempting to get ID of message before Payload is decoded");
@@ -274,7 +273,7 @@ public ACell getRequestID() {
 	 * 
 	 * This needs to work even if the payload is not yet decoded, for message routing (possibly with a different store)
 	 * 
-	 * @return
+	 * @return ID of Result, or null if no ID present
 	 */
 	public ACell getResultID() {
 		if (payload!=null) {
@@ -372,7 +371,7 @@ public boolean returnMessage(Message m) {
 
 	/**
 	 * Return true if there is encoded message data
-	 * @return
+	 * @return True if message data is constructed, false otherwise
 	 */
 	public boolean hasData() {
 		return messageData!=null;
@@ -491,7 +490,6 @@ public static Message createTransaction(long id, SignedData<ATransaction> signed
 	 * Sends a STATUS Request Message on this connection.
 	 *
 	 * @return The ID of the message sent, or -1 if send buffer is full.
-	 * @throws IOException If IO error occurs
 	 */
 	public static Message createStatusRequest(long id) {
 		CVMLong idPayload = CVMLong.create(id);
diff --git a/convex-core/src/main/java/convex/core/util/Utils.java b/convex-core/src/main/java/convex/core/util/Utils.java
@@ -633,7 +633,7 @@ public static int byteLength(long x) {
 	 * Returns the minimal number of bytes to represent the signed twos complement
 	 * value of a BigInteger
 	 *
-	 * @param x Long value
+	 * @param bi BigInteger value
 	 * @return Number of bytes required for representation, in the range 1-8
 	 *         inclusive
 	 */
diff --git a/convex-gui/src/main/java/convex/gui/peer/PeerGUI.java b/convex-gui/src/main/java/convex/gui/peer/PeerGUI.java
@@ -91,7 +91,7 @@ public static PeerGUI launchPeerGUI(int peerNum, AKeyPair genesisKey) throws Int
 	 * LAunch a peer, joining an existing network
 	 * @param sa Socket address of source peer to sync with
 	 * @param kp Key pair for new peer
-	 * @return
+	 * @return PeerGUI instance
 	 * @throws InterruptedException
 	 * @throws PeerException
 	 */
diff --git a/convex-peer/src/main/java/convex/net/AConnection.java b/convex-peer/src/main/java/convex/net/AConnection.java
@@ -22,7 +22,7 @@ public boolean isTrusted() {
 	 * @return true if message buffered successfully, false if failed due to full buffer
 	 * @throws IOException If IO error occurs while sending
 	 */
-	public abstract boolean sendMessage(Message m) throws IOException;
+	public abstract boolean sendMessage(Message msg) throws IOException;
 
 	/**
 	 * Returns the remote SocketAddress associated with this connection, or null if
diff --git a/convex-peer/src/main/java/convex/net/impl/nio/Connection.java b/convex-peer/src/main/java/convex/net/impl/nio/Connection.java
diff --git a/convex-peer/src/main/java/convex/net/impl/nio/NIOServer.java b/convex-peer/src/main/java/convex/net/impl/nio/NIOServer.java
diff --git a/convex-peer/src/main/java/convex/peer/API.java b/convex-peer/src/main/java/convex/peer/API.java
diff --git a/convex-peer/src/main/java/convex/peer/ConnectionManager.java b/convex-peer/src/main/java/convex/peer/ConnectionManager.java
diff --git a/convex-peer/src/main/java/convex/peer/Server.java b/convex-peer/src/main/java/convex/peer/Server.java
diff --git a/convex-restapi/src/main/java/convex/restapi/RESTServer.java b/convex-restapi/src/main/java/convex/restapi/RESTServer.java
