Intellisense: doc comments and inbox (server) terminology

src/main/java/com/mailosaur/Analysis.java

@@ -6,7 +6,8 @@
 import com.mailosaur.models.DeliverabilityReport;
 
 /**
- * Message analysis operations.
+ * Operations for analyzing the content and deliverability of an email, including SpamAssassin
+ * scoring and per-provider deliverability reports. Accessed via {@link MailosaurClient#analysis()}.
  */
 public class Analysis {
     private MailosaurClient client;

src/main/java/com/mailosaur/Devices.java

@@ -8,6 +8,11 @@
 import java.io.IOException;
 import java.util.HashMap;
 
+/**
+ * Operations for managing virtual security devices and retrieving their current one-time
+ * passwords (OTPs), used to automate testing of app-based multi-factor authentication.
+ * Accessed via {@link MailosaurClient#devices()}.
+ */
 public class Devices {
     private MailosaurClient client;
 
@@ -39,12 +44,13 @@ public Device create(DeviceCreateOptions options) throws IOException, MailosaurE
     }
 
     /**
-     * Retrieve the current one-time password.
+     * Retrieves the current one-time password for a saved device, or given a base32-encoded
+     * shared secret.
      *
      * @param query Either the unique identifier of the device, or a base32-encoded shared secret.
      * @throws MailosaurException Thrown if Mailosaur responds with an error.
      * @throws IOException Unexpected exception.
-     * @return The current one-time password.
+     * @return An {@link OtpResult} containing the current one-time password.
      */
     public OtpResult otp(String query) throws IOException, MailosaurException {
         if (query.contains("-")) {

src/main/java/com/mailosaur/Files.java

@@ -10,7 +10,9 @@
 import java.util.List;
 
 /**
- * File operations.
+ * Operations for downloading the raw content associated with a message — file attachments,
+ * the full EML source of an email, and rendered email previews. Accessed via
+ * {@link MailosaurClient#files()}.
  */
 public class Files {
     private MailosaurClient client;
@@ -48,9 +50,10 @@ public byte[] getEmail(String messageId) throws MailosaurException, IOException
      * the unique identifier for the required preview.
      *
      * @param previewId The identifier of the email preview to be downloaded.
-     * @throws MailosaurException Thrown if Mailosaur responds with an error.
+     * @throws MailosaurException With error code {@code preview_timeout} if the preview is not
+     *     generated within the time limit.
      * @throws IOException Unexpected exception.
-     * @return The byte array if successful.
+     * @return A byte array containing the preview screenshot image.
      */
     public byte[] getPreview(String previewId) throws MailosaurException, IOException {
         int timeout = 120000;

src/main/java/com/mailosaur/MailosaurClient.java

@@ -19,6 +19,13 @@
 import com.google.gson.JsonParser;
 import com.mailosaur.models.MessageSummary;
 
+/**
+ * The Mailosaur client — the main entry point to the Mailosaur API. Construct an instance
+ * with your API key (or set the {@code MAILOSAUR_API_KEY} environment variable), then use the
+ * operations namespaces ({@link #messages()}, {@link #servers()}, {@link #files()},
+ * {@link #devices()}, {@link #analysis()}, {@link #previews()}, {@link #usage()}) to automate
+ * email and SMS testing.
+ */
 public class MailosaurClient {
     final String VERSION = "9.0.0";
 	final String API_KEY;
@@ -82,91 +89,98 @@ private static String resolveApiKeyFromEnv() throws MailosaurException {
 	}
 
 	/**
-     * Message analysis operations
+     * Operations for analyzing email content and deliverability, including spam scoring.
      */
     private Analysis analysis;
 
     /**
-     * Gets message analysis operations.
-     * @return Message analysis operations.
+     * Gets the operations for analyzing email content and deliverability, including spam scoring.
+     *
+     * @return The {@link Analysis} operations namespace.
      */
     public Analysis analysis() {
         return this.analysis;
     }
 
     /**
-     * File operations
+     * Operations for downloading attachments, EML source, and email preview screenshots.
      */
     private Files files;
 
     /**
-     * Gets file operations.
-     * @return File operations.
+     * Gets the operations for downloading attachments, EML source, and email preview screenshots.
+     *
+     * @return The {@link Files} operations namespace.
      */
     public Files files() {
         return this.files;
     }
 
     /**
-     * Message operations
+     * Operations for finding, retrieving, creating, and managing email and SMS messages.
      */
     private Messages messages;
 
     /**
-     * Gets message operations.
-     * @return Message operations.
+     * Gets the operations for finding, retrieving, creating, and managing email and SMS messages.
+     *
+     * @return The {@link Messages} operations namespace.
      */
     public Messages messages() {
         return this.messages;
     }
 
     /**
-     * Server management operations
+     * Operations for creating and managing your Mailosaur inboxes (servers).
      */
     private Servers servers;
 
     /**
-     * Gets server management operations.
-     * @return Server management operations.
+     * Gets the operations for creating and managing your Mailosaur inboxes (servers).
+     *
+     * @return The {@link Servers} operations namespace.
      */
     public Servers servers() {
         return this.servers;
     }
 
     /**
-     * Account usage operations
+     * Operations for inspecting account usage limits and recent transactional usage.
      */
     private Usage usage;
 
     /**
-     * Gets account usage operations.
-     * @return Account usage operations.
+     * Gets the operations for inspecting account usage limits and recent transactional usage.
+     *
+     * @return The {@link Usage} operations namespace.
      */
     public Usage usage() {
         return this.usage;
     }
 
     /**
-     * Device management operations
+     * Operations for managing virtual security devices and retrieving their one-time passwords.
      */
     private Devices devices;
 
     /**
-     * Gets device management operations.
-     * @return Device management operations.
+     * Gets the operations for managing virtual security devices and retrieving their one-time passwords.
+     *
+     * @return The {@link Devices} operations namespace.
      */
     public Devices devices() {
         return this.devices;
     }
 
     /**
-     * Email Previews operations
+     * Operations for discovering the email clients available for generating email previews.
      */
     private Previews previews;
 
     /**
-     * Gets Email Previews operations.
-     * @return Email Previews operations.
+     * Gets the operations for discovering the email clients available for generating email previews.
+     *
+     * @return The {@link Previews} operations namespace.
      */
     public Previews previews() {
         return this.previews;