From 2a0cfd3a32bb4eb48e861ee694ab0849378c1c56 Mon Sep 17 00:00:00 2001
From: Maarten Billemont <lhunath@lyndir.com>
Date: Sat, 22 Sep 2018 19:41:48 -0400
Subject: [PATCH] Documentation and interface tweaks.

---
 .../lyndir/masterpassword/MPMasterKey.java    |  2 ++
 .../lyndir/masterpassword/model/MPSite.java   |  7 +++++--
 .../model/impl/MPBasicSite.java               | 20 ++++++++++++-------
 .../masterpassword/model/impl/MPFileSite.java |  2 +-
 4 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/platform-independent/java/algorithm/src/main/java/com/lyndir/masterpassword/MPMasterKey.java b/platform-independent/java/algorithm/src/main/java/com/lyndir/masterpassword/MPMasterKey.java
index 32147cf6..8d4fde49 100644
--- a/platform-independent/java/algorithm/src/main/java/com/lyndir/masterpassword/MPMasterKey.java
+++ b/platform-independent/java/algorithm/src/main/java/com/lyndir/masterpassword/MPMasterKey.java
@@ -147,6 +147,7 @@ public class MPMasterKey {
      * @return {@code null} if the result type is missing a required parameter.
      *
      * @throws MPKeyUnavailableException {@link #invalidate()} has been called on this object.
+     * @throws MPAlgorithmException An internal system or algorithm error has occurred.
      */
     @Nullable
     public String siteResult(final String siteName, final MPAlgorithm algorithm, final UnsignedInteger siteCounter,
@@ -184,6 +185,7 @@ public class MPMasterKey {
      *                    {@link #siteResult(String, MPAlgorithm, UnsignedInteger, MPKeyPurpose, String, MPResultType, String)}.
      *
      * @throws MPKeyUnavailableException {@link #invalidate()} has been called on this object.
+     * @throws MPAlgorithmException An internal system or algorithm error has occurred.
      */
     @Nonnull
     public String siteState(final String siteName, final MPAlgorithm algorithm, final UnsignedInteger siteCounter,
diff --git a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/MPSite.java b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/MPSite.java
index 9955f437..f93f3f1d 100644
--- a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/MPSite.java
+++ b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/MPSite.java
@@ -80,6 +80,9 @@ public interface MPSite<Q extends MPQuestion> extends Comparable<MPSite<?>> {
     String getResult(MPKeyPurpose keyPurpose, @Nullable String keyContext, @Nullable String state)
             throws MPKeyUnavailableException, MPAlgorithmException;
 
+    /**
+     * @see MPMasterKey#siteResult(String, MPAlgorithm, UnsignedInteger, MPKeyPurpose, String, MPResultType, String)
+     */
     @Nullable
     String getResult(MPKeyPurpose keyPurpose, @Nullable String keyContext,
                      @Nullable UnsignedInteger counter, MPResultType type, @Nullable String state)
@@ -90,13 +93,13 @@ public interface MPSite<Q extends MPQuestion> extends Comparable<MPSite<?>> {
                     @Nullable UnsignedInteger counter, MPResultType type, String state)
             throws MPKeyUnavailableException, MPAlgorithmException;
 
-    @Nonnull
+    @Nullable
     default String getLogin()
             throws MPKeyUnavailableException, MPAlgorithmException {
         return getLogin( null );
     }
 
-    @Nonnull
+    @Nullable
     String getLogin(@Nullable String state)
             throws MPKeyUnavailableException, MPAlgorithmException;
 
diff --git a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPBasicSite.java b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPBasicSite.java
index 2fae0e25..5f1d5450 100644
--- a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPBasicSite.java
+++ b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPBasicSite.java
@@ -62,12 +62,16 @@ public abstract class MPBasicSite<U extends MPUser<?>, Q extends MPQuestion> ext
         this.loginType = (loginType != null)? loginType: this.algorithm.mpw_default_login_type();
     }
 
+    // - Meta
+
     @Nonnull
     @Override
     public String getSiteName() {
         return siteName;
     }
 
+    // - Algorithm
+
     @Nonnull
     @Override
     public MPAlgorithm getAlgorithm() {
@@ -158,7 +162,7 @@ public abstract class MPBasicSite<U extends MPUser<?>, Q extends MPQuestion> ext
                 keyPurpose, keyContext, type, state );
     }
 
-    @Nonnull
+    @Nullable
     @Override
     public String getLogin(@Nullable final String state)
             throws MPKeyUnavailableException, MPAlgorithmException {
@@ -166,6 +170,14 @@ public abstract class MPBasicSite<U extends MPUser<?>, Q extends MPQuestion> ext
         return getResult( MPKeyPurpose.Identification, null, null, getLoginType(), state );
     }
 
+    // - Relations
+
+    @Nonnull
+    @Override
+    public U getUser() {
+        return user;
+    }
+
     @Nonnull
     @Override
     public Q addQuestion(final Q question) {
@@ -200,12 +212,6 @@ public abstract class MPBasicSite<U extends MPUser<?>, Q extends MPQuestion> ext
         return results.build();
     }
 
-    @Nonnull
-    @Override
-    public U getUser() {
-        return user;
-    }
-
     @Override
     protected void onChanged() {
         super.onChanged();
diff --git a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPFileSite.java b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPFileSite.java
index 595216d1..d7bb7f44 100644
--- a/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPFileSite.java
+++ b/platform-independent/java/model/src/main/java/com/lyndir/masterpassword/model/impl/MPFileSite.java
@@ -101,7 +101,7 @@ public class MPFileSite extends MPBasicSite<MPFileUser, MPFileQuestion> {
         return getResult( keyPurpose, keyContext, getResultState() );
     }
 
-    @Nonnull
+    @Nullable
     @Override
     public String getLogin()
             throws MPKeyUnavailableException, MPAlgorithmException {