Preparing for 0.7.13 release, doc fixes

convex-benchmarks/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>world.convex</groupId>
 		<artifactId>convex</artifactId>
-		<version>0.7.13-SNAPSHOT</version>
+		<version>0.7.13</version>
 	</parent>
 
 	<modelVersion>4.0.0</modelVersion>

convex-cli/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<groupId>world.convex</groupId>
 		<artifactId>convex</artifactId>
-		<version>0.7.13-SNAPSHOT</version>
+		<version>0.7.13</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

convex-cli/src/main/java/convex/cli/ACommand.java

@@ -7,7 +7,7 @@ public abstract class ACommand implements Runnable {
 
 	/**
 	 * Gets the current CLI main command instance
-	 * @return
+	 * @return CLI instance
 	 */
 	public abstract Main cli();
 }

convex-core/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>world.convex</groupId>
 		<artifactId>convex</artifactId>
-		<version>0.7.13-SNAPSHOT</version>
+		<version>0.7.13</version>
 	</parent>
 
 	<properties>

convex-core/src/main/java/convex/core/Block.java

@@ -150,7 +150,7 @@ public int estimatedEncodingSize() {
 
 	/**
 	 * Read a Block from a Blob encoding
-	 * @throws BadFormatException
+	 * @throws BadFormatException In event of encoding error
 	 */
 	public static Block read(Blob b, int pos) throws BadFormatException {
 		int epos=pos+1; // skip tag

convex-core/src/main/java/convex/core/Receipt.java

@@ -68,7 +68,7 @@ private AVector<AVector<ACell>> getLog() {
 
 	/**
 	 * Gets the error code of this Receipt, or null if not an error
-	 * @return
+	 * @return Error code (probably a Keyword or nil)
 	 */
 	public ACell getErrorCode() {
 		if (!isError) return null;
@@ -77,7 +77,7 @@ public ACell getErrorCode() {
 
 	/**
 	 * Gets the result value of this Receipt, or null if an error
-	 * @return
+	 * @return Result from this Receipt
 	 */
 	public ACell getResult() {
 		if (isError) return null;

convex-core/src/main/java/convex/core/Result.java

@@ -258,7 +258,7 @@ public boolean isError() {
 	/**
 	 * Constructs a Result from a Context
 	 * @param id Id for Result
-	 * @param ctx Context
+	 * @param rc ResultContext instance from which to extract Result
 	 * @return New Result instance
 	 */
 

convex-core/src/main/java/convex/core/State.java

@@ -312,8 +312,8 @@ public BlockResult applyBlock(SignedData<Block> signedBlock) {
 
 	/**
 	 * Checks if a block is valid for application to the current state
-	 * @param signedBlock
-	 * @return
+	 * @param signedBlock Signed Block
+	 * @return BlockResult instance if an error occurred, or nil if checks pass
 	 */
 	public BlockResult checkBlock(SignedData<Block> signedBlock) {
 		Block block=signedBlock.getValue();
@@ -544,7 +544,7 @@ private ResultContext createResultContext(ATransaction t) {
 	 *
 	 * There are three phases in application of a transaction:
 	 * <ol>
-	 * <li>Preparation for accounting, with {@link #prepareTransaction(ATransaction) prepareTransaction}</li>
+	 * <li>Preparation for accounting, with {@link #prepareTransaction(ResultContext) prepareTransaction}</li>
 	 * <li>Functional application of the transaction with ATransaction.apply(....)</li>
 	 * <li>Completion of accounting, with completeTransaction</li>
 	 * </ol>

convex-core/src/main/java/convex/core/crypto/BIP39.java

@@ -226,8 +226,6 @@ public class BIP39 {
 	 * @param words Mnemonic words
 	 * @param passphrase Optional BIP39 passphrase
 	 * @return Blob containing BIP39 seed (64 bytes)
-	 * @throws NoSuchAlgorithmException
-	 * @throws InvalidKeySpecException
 	 */
 	public static Blob getSeed(List<String> words, String passphrase) throws NoSuchAlgorithmException, InvalidKeySpecException {
 		if (passphrase==null) passphrase="";
@@ -264,7 +262,7 @@ public static Blob seedToEd25519Seed(Blob seed) {
 
 	/**
 	 * Return true if the string is a valid mnemonic phrase
-	 * @param menemonic
+	 * @param s String to be tested as a mnemonic phrase
 	 * @return String containing reason that mnemonic is not valid, or null if OK
 	 */
 	public static String checkMnemonic(String s) {
@@ -278,8 +276,6 @@ public static String checkMnemonic(String s) {
 	 * @param mnemonic Mnemonic words
 	 * @param passphrase Optional BIP39 passphrase
 	 * @return Blob containing BIP39 seed (64 bytes)
-	 * @throws NoSuchAlgorithmException
-	 * @throws InvalidKeySpecException
 	 */
 	public static Blob getSeed(String mnemonic, String passphrase) {
 			mnemonic=normalise(mnemonic);

convex-core/src/main/java/convex/core/crypto/Ed25519Signature.java

@@ -47,7 +47,7 @@ public static Ed25519Signature wrap(byte[] signature) {
 
 	/**
 	 * Creates a Signature instance with specific bytes
-	 * @param signature Bytes for signature
+	 * @param data Bytes for signature
 	 * @return Signature instance
 	 */
 	public static Ed25519Signature wrap(byte[] data, int pos) {

convex-core/src/main/java/convex/core/crypto/PFXTools.java

@@ -27,7 +27,7 @@ public class PFXTools {
 	/**
 	 * Creates a new PKCS12 key store.
 	 * @param keyFile File to use for creating the key store
-	 * @param passPhrase Passphrase used to protect the key store, may be null
+	 * @param storePassword Passphrase used to protect the key store, may be null
 	 * @return New KeyStore instance
 	 */
 	public static KeyStore createStore(File keyFile, char[] storePassword) throws GeneralSecurityException, IOException {
@@ -85,7 +85,7 @@ public static KeyStore saveStore(KeyStore ks, File keyFile, char[] storePassword
 	 * Retrieves a key pair from a key store.
 	 * @param ks Key store
 	 * @param alias Alias used for finding the key pair in the store
-	 * @param passphrase Passphrase used for decrypting the key pair. Mandatory.
+	 * @param keyPassword Passphrase used for decrypting the key pair. Mandatory.
 	 * @return Found key pair
 	 * @throws UnrecoverableKeyException If key cannot be recovered
 	 * @throws KeyStoreException If a general key store exception occurs
@@ -116,7 +116,7 @@ public static KeyStore setKeyPair(KeyStore ks, AKeyPair kp, char[] keyPassword)
 	 * @param ks Key store
 	 * @param alias Alias entry for keystore
 	 * @param kp Key pair
-	 * @param passPhrase Passphrase for encrypting the key pair. Mandatory.
+	 * @param keyPassword Password for encrypting the key pair. Mandatory.
 	 * @return Updated key store.
 	 * @throws IOException If an IO error occurs accessing the key store
 	 * @throws GeneralSecurityException if a security exception occurs

convex-core/src/main/java/convex/core/crypto/SLIP10.java

@@ -2,8 +2,6 @@
 
 import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
-import java.security.InvalidKeyException;
-import java.security.NoSuchAlgorithmException;
 
 import javax.crypto.Mac;
 import javax.crypto.spec.SecretKeySpec;
@@ -30,8 +28,6 @@ public class SLIP10 {
 	 * Gets the the master key for a given seed according to SLIP10
 	 * @param seed BIP39 seed value (or other source of good entropy!)
 	 * @return Blob containing the seed (bip39 seed, or some other good entropy source)
-	 * @throws NoSuchAlgorithmException
-	 * @throws InvalidKeyException
 	 */
 	public static Blob getMaster(Blob seed) {
 		try {

convex-core/src/main/java/convex/core/crypto/wallet/IWalletEntry.java

@@ -7,7 +7,7 @@ public interface IWalletEntry {
 
 	/**
 	 * Check if this wallet entry is locked.
-	 * @return
+	 * @return True if wallet is locked
 	 */
 	public boolean isLocked();
 
@@ -19,27 +19,27 @@ public interface IWalletEntry {
 
 	/**
 	 * Get the public key associated with this wallet entry
-	 * @return
+	 * @return Public Key
 	 */
 	AccountKey getPublicKey();
 
 	/**
 	 * Try to unlock a wallet with the given password
+	 * @param password Password to unlock
 	 * 
 	 * @return true if unlocked, false otherwise
 	 */
 	public boolean tryUnlock(char[] password);
 
 	/**
 	 * Unlock the wallet entry. Unlocking makes the entry usable for signing
-	 * @param passPhrase
-	 * @return 
+	 * @param password Unlock password
 	 */
-	public void unlock(char[] passPhrase);
+	public void unlock(char[] password);
 
 	/**
 	 * Lock the wallet entry. Locking makes the wallet entry unusable until unlocked.
-	 * @param password
+	 * @param password Password with which to lock wallet
 	 */
 	public void lock(char[] password);
 

convex-core/src/main/java/convex/core/data/ADataStructure.java

@@ -60,7 +60,6 @@ public final boolean isEmpty() {
 	 * Adds an element to this data structure, in the natural manner defined by the
 	 * general data structure type. e.g. append at the end of a vector.
 	 * 
-	 * @param <R> Type of Value added
 	 * @param x New element to add
 	 * @return The updated data structure, or null if a failure occurred due to invalid element type
 	 */
@@ -72,7 +71,6 @@ public final boolean isEmpty() {
 	 * 
 	 * This may be more efficient than using 'conj' for individual items.
 	 * 
-	 * @param <R> Type of Value added
 	 * @param xs New elements to add
 	 * @return The updated data structure, or null if a failure occurred due to invalid element types
 	 */

convex-core/src/main/java/convex/core/data/AVector.java

@@ -66,7 +66,7 @@ public AType getType() {
 	 * Appends a ListVector chunk to this vector. This vector must contain a whole
 	 * number of chunks
 	 * 
-	 * @param listVector A chunk to append. Must be a ListVector of maximum size
+	 * @param chunk A chunk to append. Must be a ListVector of maximum size
 	 * @return The updated vector, of the same type as this vector @
 	 */
 	public abstract AVector<T> appendChunk(AVector<T> chunk);

convex-core/src/main/java/convex/core/data/Cells.java

@@ -81,11 +81,11 @@ public static int branchCount(ACell a) {
 
 	/**
 	 * Gets a Ref from a Cell by index
-	 * @param <R>
+	 * @param <R> Type of cell
 	 * @param cell Cell to read Ref from
 	 * @param index Numerical index of Ref
 	 * @throws IndexOutOfBoundsException if the index is out of range for the Cell
-	 * @return
+	 * @return Ref for cell
 	 */
 	public static <R extends ACell> Ref<R> getRef(ACell cell, int index) {
 		if (cell ==null) throw new IndexOutOfBoundsException("Bad ref index called on null");
@@ -126,7 +126,6 @@ public static boolean isValue(ACell a) {
 	 * Persist a cell in the current store
 	 * @param a Cell to persist
 	 * @return Cell after persisting (may be the same Cell if no change in cell hierarchy)
-	 * @throws MissingDataException if the cell cannot be fully persisted due to missing data
 	 */
 	public static <T extends ACell> T persist(T a) {
 		return persist(a,Stores.current());
@@ -137,7 +136,6 @@ public static <T extends ACell> T persist(T a) {
 	 * @param a Cell to persist
 	 * @param store Store instance to persist in
 	 * @return Cell after persisting (may be the same Cell if no change in cell hierarchy)
-	 * @throws MissingDataException if the cell cannot be fully persisted due to missing data
 	 */
 	public static <T extends ACell> T persist(T a, AStore store) {
 		Ref<T> ref=Ref.get(a);
@@ -150,7 +148,6 @@ public static <T extends ACell> T persist(T a, AStore store) {
 	 * @param a Cell to persist
 	 * @param store Store instance to persist in
 	 * @return Cell after persisting (may be the same Cell if no change in cell hierarchy)
-	 * @throws MissingDataException if the cell cannot be fully persisted due to missing data
 	 */
 	public static <T extends ACell> T store(T a, AStore store) {
 		Ref<T> ref=Ref.get(a);
@@ -163,7 +160,6 @@ public static <T extends ACell> T store(T a, AStore store) {
 	 * @param a Cell to announce
 	 * @param noveltyHandler Handler for novelty values
 	 * @return Cell after announcing (may be the same Cell if no change in cell hierarchy)
-	 * @throws MissingDataException if the cell cannot be fully persisted due to missing data
 	 */
 	public static <T extends ACell> T announce(T a, Consumer<Ref<ACell>> noveltyHandler) {
 		if (a==null) {
@@ -190,8 +186,8 @@ public static ABlobLike<CVMLong> getEncoding(ACell a) {
 
 	/**
 	 * Get the full storage size of a value, including size of an embedded encoding
-	 * @param a
-	 * @return
+	 * @param a Cell to get size for (may be null)
+	 * @return Storage size
 	 */
 	public static long storageSize(ACell a) {
 		if (a==null) return 1;

convex-core/src/main/java/convex/core/data/Format.java

@@ -798,7 +798,7 @@ public static int estimateEncodingSize(ACell cell) {
 	 * Decodes an array of Cells packed in a Blob. Cells may be partial.
 	 * @param data Data containing cell encodings in multi-cell format
 	 * @return Array of decoded cells
-	 * @throws BadFormatException
+	 * @throws BadFormatException In event of any encoding error detected
 	 */
 	public static ACell[] decodeCells(Blob data) throws BadFormatException {
 		long ml=data.count();

convex-core/src/main/java/convex/core/data/Index.java

@@ -265,7 +265,7 @@ public Index<K, V> dissoc(K k) {
 	 * Tests if two keys match (up to the maximum index key depth)
 	 * @param a First key
 	 * @param b second key
-	 * @return
+	 * @return True if keys match
 	 */
 	public static <K extends ABlobLike<?>>boolean keyMatch(K a, K b) {
 		long n=a.count();

convex-core/src/main/java/convex/core/data/Ref.java

@@ -619,7 +619,7 @@ public long getMemorySize() {
 	/**
 	 * Finds all instances of missing data in this Ref, and adds them to the missing set
 	 * @param missingSet Set to add missing instances to
-	 * @param limit 
+	 * @param limit Maximum number of missing branches to identity
 	 */
 	public void findMissing(HashSet<Hash> missingSet, long limit) {
 		if (getStatus()>=Ref.PERSISTED) return;

convex-core/src/main/java/convex/core/data/SignedData.java

@@ -245,7 +245,8 @@ public boolean checkSignature() {
 
 	/**
 	 * Validates the signature in this SignedData instance. Caches result
-	 *
+	 * 
+	 * @param publicKey Public key to check against this signature
 	 * @return true if valid, false otherwise
 	 */
 	public boolean checkSignature(AccountKey publicKey) {

convex-core/src/main/java/convex/core/data/VectorArray.java

@@ -17,7 +17,7 @@
  * 
  * Directly wraps an array of cells, considered effectively immutable
  * 
- * @param <T>
+ * @param <T> Type of vector elements
  */
 public class VectorArray<T extends ACell> extends ASpecialVector<T> {
 

convex-core/src/main/java/convex/core/data/prim/AInteger.java

@@ -184,7 +184,7 @@ public static AInteger create(Number value) {
 
 	/**
 	 * Raise the integer to the given power
-	 * @param power
+	 * @param power Power to raise integer to
 	 * @return Result, or null if invalid
 	 */
 	public AInteger toPower(AInteger power) {

convex-core/src/main/java/convex/core/data/prim/CVMChar.java

@@ -75,7 +75,7 @@ public static CVMChar create(long value) {
 
 	/**
 	 * Gets a {@link CVMChar} from a UTF-8 representation
-	 * @param value UTF-8 representation of a single character
+	 * @param b Representation of a single character (UTF-8)
 	 * @return CVMChar instance, or null if not valid
 	 */
 	public static CVMChar fromUTF8(ABlobLike<?> b) {

convex-core/src/main/java/convex/core/lang/Context.java

@@ -319,7 +319,6 @@ public static Context createInitial(State state, Address origin,long juiceLimit)
 	 * <li>Accumulates used juice fees in globals</li>
 	 * <li>Increments sequence number</li>
 	 * </ul>
-	 * @param t 
 	 *
 	 * @param initialState State before transaction execution (after prepare)
 	 * @param rc Juice price of current execution
@@ -634,7 +633,7 @@ private Address getParentAddress(AccountStatus as) {
 
 	/**
 	 * Looks up value for the given symbol in this context
-	 * @param sym Symbol name to look up, as a Java String for convenience
+	 * @param symName Symbol name to look up, as a Java String for convenience
 	 * @return Value for the given symbol or null if undeclared
 	 */
 	@SuppressWarnings("unchecked")
@@ -1320,9 +1319,9 @@ public Context eval(ACell form) {
 
 	/**
 	 * Executes an op as a top level instruction (no local bindings)
-	 * @param <T>
-	 * @param op
-	 * @return
+	 * @param <T> Type of Op result
+	 * @param op Op to execute
+	 * @return Updated Context
 	 */
 	public <T extends ACell> Context exec(AOp<T> op) {
 		AVector<ACell> savedBindings = getLocalBindings();