Update ContactManager javadocs.

bramble-api/src/main/java/org/briarproject/bramble/api/contact/ContactManager.java

@@ -30,10 +30,16 @@ public interface ContactManager {
 
 	/**
 	 * Stores a contact associated with the given local and remote pseudonyms,
-	 * derives and stores transport keys for each transport, and returns an ID
+	 * derives and stores rotation mode transport keys for each transport, and
-	 * for the contact.
+	 * returns an ID for the contact.
 	 *
+	 * @param rootKey The root key for a set of rotation mode transport keys
+	 * @param timestamp The timestamp for deriving rotation mode transport
+	 * keys from the root key
 	 * @param alice True if the local party is Alice
+	 * @param verified True if the contact's identity has been verified
+	 * @param active True if the rotation mode transport keys can be used for
+	 * outgoing streams
 	 */
 	ContactId addContact(Transaction txn, Author remote, AuthorId local,
 			SecretKey rootKey, long timestamp, boolean alice, boolean verified,
@@ -41,10 +47,17 @@ public interface ContactManager {
 
 	/**
 	 * Stores a contact associated with the given local and remote pseudonyms,
-	 * replacing the given pending contact, derives and stores transport keys
+	 * replacing the given pending contact, derives and stores handshake mode
-	 * for each transport, and returns an ID for the contact.
+	 * and rotation mode transport keys for each transport, and returns an ID
+	 * for the contact.
 	 *
+	 * @param rootKey The root key for a set of rotation mode transport keys
+	 * @param timestamp The timestamp for deriving rotation mode transport
+	 * keys from the root key
 	 * @param alice True if the local party is Alice
+	 * @param verified True if the contact's identity has been verified
+	 * @param active True if the rotation mode transport keys can be used for
+	 * outgoing streams
 	 * @throws GeneralSecurityException If the pending contact's handshake
 	 * public key is invalid
 	 */
@@ -56,16 +69,24 @@ public interface ContactManager {
 	/**
 	 * Stores a contact associated with the given local and remote pseudonyms
 	 * and returns an ID for the contact.
+	 *
+	 * @param verified True if the contact's identity has been verified
 	 */
 	ContactId addContact(Transaction txn, Author remote, AuthorId local,
 			boolean verified) throws DbException;
 
 	/**
 	 * Stores a contact associated with the given local and remote pseudonyms,
-	 * derives and stores transport keys for each transport, and returns an ID
+	 * derives and stores rotation mode transport keys for each transport, and
-	 * for the contact.
+	 * returns an ID for the contact.
 	 *
+	 * @param rootKey The root key for a set of rotation mode transport keys
+	 * @param timestamp The timestamp for deriving rotation mode transport
+	 * keys from the root key
 	 * @param alice True if the local party is Alice
+	 * @param verified True if the contact's identity has been verified
+	 * @param active True if the rotation mode transport keys can be used for
+	 * outgoing streams
 	 */
 	ContactId addContact(Author remote, AuthorId local, SecretKey rootKey,
 			long timestamp, boolean alice, boolean verified, boolean active)
@@ -81,9 +102,8 @@ public interface ContactManager {
 	 * Creates a {@link PendingContact} from the given handshake link and
 	 * alias, adds it to the database and returns it.
 	 *
-	 * @param link The handshake link received from the contact we want to add
+	 * @param link The handshake link received from the pending contact
-	 * @param alias The alias the user has given this contact
+	 * @param alias The alias the user has given this pending contact
-	 * @return A PendingContact representing the contact to be added
 	 * @throws UnsupportedVersionException If the link uses a format version
 	 * that is not supported
 	 * @throws FormatException If the link is invalid
@@ -122,8 +142,8 @@ public interface ContactManager {
 	Contact getContact(Transaction txn, ContactId c) throws DbException;
 
 	/**
-	 * Returns the contact with the given remoteAuthorId
+	 * Returns the contact with the given {@code remoteAuthorId}
-	 * that was added by the LocalAuthor with the given localAuthorId
+	 * that belongs to the local pseudonym with the given {@code localAuthorId}.
 	 *
 	 * @throws NoSuchContactException If the contact is not in the database
 	 */
@@ -131,8 +151,8 @@ public interface ContactManager {
 			throws DbException;
 
 	/**
-	 * Returns the contact with the given remoteAuthorId
+	 * Returns the contact with the given {@code remoteAuthorId}
-	 * that was added by the LocalAuthor with the given localAuthorId
+	 * that belongs to the local pseudonym with the given {@code localAuthorId}.
 	 *
 	 * @throws NoSuchContactException If the contact is not in the database
 	 */
@@ -140,7 +160,7 @@ public interface ContactManager {
 			AuthorId localAuthorId) throws DbException;
 
 	/**
-	 * Returns all active contacts.
+	 * Returns all contacts.
 	 */
 	Collection<Contact> getContacts() throws DbException;
 
@@ -155,25 +175,27 @@ public interface ContactManager {
 	void removeContact(Transaction txn, ContactId c) throws DbException;
 
 	/**
-	 * Sets an alias for the contact or unsets it if alias is null.
+	 * Sets an alias for the contact or unsets it if {@code alias} is null.
 	 */
 	void setContactAlias(Transaction txn, ContactId c, @Nullable String alias)
 			throws DbException;
 
 	/**
-	 * Sets an alias for the contact or unsets it if alias is null.
+	 * Sets an alias for the contact or unsets it if {@code alias} is null.
 	 */
 	void setContactAlias(ContactId c, @Nullable String alias)
 			throws DbException;
 
 	/**
-	 * Return true if a contact with this name and public key already exists
+	 * Returns true if a contact with this {@code remoteAuthorId} belongs to
+	 * the local pseudonym with this {@code localAuthorId}.
 	 */
 	boolean contactExists(Transaction txn, AuthorId remoteAuthorId,
 			AuthorId localAuthorId) throws DbException;
 
 	/**
-	 * Return true if a contact with this name and public key already exists
+	 * Returns true if a contact with this {@code remoteAuthorId} belongs to
+	 * the local pseudonym with this {@code localAuthorId}.
 	 */
 	boolean contactExists(AuthorId remoteAuthorId, AuthorId localAuthorId)
 			throws DbException;