Add references to Sonos docs for all endpoints, and start adding Javadoc throughout

Author: nightowlengineer

src/main/java/engineer/nightowl/sonos/api/SonosApiClient.java

@@ -34,7 +34,7 @@ public class SonosApiClient
     /**
      * Main client for Sonos API.
      *
-     * @param configuration - a {@link SonosApiConfiguration} containing integration
+     * @param configuration - a {@link engineer.nightowl.sonos.api.SonosApiConfiguration} containing integration
      *                      information such as API keys
      */
     public SonosApiClient(final SonosApiConfiguration configuration)
@@ -97,6 +97,8 @@ public CloseableHttpClient getHttpClient()
 
     /**
      * Set a custom HTTP client.
+     *
+     * @param httpClient custom client to set
      */
     public void setHttpClient(final CloseableHttpClient httpClient)
     {
@@ -125,9 +127,9 @@ public SonosApiConfiguration getConfiguration()
     }
 
     /**
-     * Set a new {@link SonosApiConfiguration}.
+     * Set a new {@link engineer.nightowl.sonos.api.SonosApiConfiguration}.
      *
-     * @param configuration - the new {@link SonosApiConfiguration}
+     * @param configuration - the new {@link engineer.nightowl.sonos.api.SonosApiConfiguration}
      */
     public void setConfiguration(final SonosApiConfiguration configuration)
     {
@@ -147,6 +149,8 @@ public AuthorizeResource authorize()
 
     /**
      * Manage a household's favorites.
+     *
+     * @return the FavoriteResource
      */
     public FavoriteResource favorite()
     {
@@ -155,6 +159,8 @@ public FavoriteResource favorite()
 
     /**
      * Manage a household's groups.
+     *
+     * @return the GroupResource
      */
     public GroupResource group()
     {
@@ -163,6 +169,8 @@ public GroupResource group()
 
     /**
      * Manage the volume of a group
+     *
+     * @return the GroupVolumeResource
      */
     public GroupVolumeResource groupVolumeResource()
     {
@@ -171,6 +179,8 @@ public GroupVolumeResource groupVolumeResource()
 
     /**
      * Manage home theater features
+     *
+     * @return the HomeTheaterResource
      */
     public HomeTheaterResource homeTheater()
     {
@@ -179,6 +189,8 @@ public HomeTheaterResource homeTheater()
 
     /**
      * Manage a user's household(s)
+     *
+     * @return the HouseholdResource
      */
     public HouseholdResource household()
     {
@@ -187,6 +199,8 @@ public HouseholdResource household()
 
     /**
      * Match music service accounts
+     *
+     * @return the MusicServiceAccountsResource
      */
     public MusicServiceAccountsResource musicServiceAccounts()
     {
@@ -195,6 +209,8 @@ public MusicServiceAccountsResource musicServiceAccounts()
 
     /**
      * Subscribe/unsubscribe to playback events
+     *
+     * @return the PlaybackMetadataResource
      */
     public PlaybackMetadataResource playbackMetadata()
     {
@@ -203,6 +219,8 @@ public PlaybackMetadataResource playbackMetadata()
 
     /**
      * Manage the playback of the system.
+     *
+     * @return the PlaybackResource
      */
     public PlaybackResource playback()
     {
@@ -211,6 +229,8 @@ public PlaybackResource playback()
 
     /**
      * Manage playback sessions.
+     *
+     * @return the PlaybackSessionResource
      */
     public PlaybackSessionResource playbackSession()
     {
@@ -219,6 +239,8 @@ public PlaybackSessionResource playbackSession()
 
     /**
      * Manage player volume.
+     *
+     * @return the PlayerVolumeResource
      */
     public PlayerVolumeResource playerVolume()
     {

src/main/java/engineer/nightowl/sonos/api/SonosApiConfiguration.java

@@ -5,7 +5,7 @@
 import org.apache.http.message.BasicHeader;
 
 /**
- * Configuration class to be built up and passed into a {@link SonosApiClient}
+ * Configuration class to be built up and passed into a {@link engineer.nightowl.sonos.api.SonosApiClient}
  * <p>
  * Loads defaults on construction.
  */
@@ -18,26 +18,49 @@ public class SonosApiConfiguration
     private String authBaseUrl;
     private String controlBaseUrl;
 
+    /**
+     * <p>Constructor for SonosApiConfiguration.</p>
+     */
     public SonosApiConfiguration()
     {
         loadDefaults();
     }
 
+    /**
+     * <p>Getter for the field <code>applicationId</code>.</p>
+     *
+     * @return a {@link java.lang.String} object.
+     */
     public String getApplicationId()
     {
         return applicationId;
     }
 
+    /**
+     * <p>Setter for the field <code>applicationId</code>.</p>
+     *
+     * @param applicationId a {@link java.lang.String} object.
+     */
     public void setApplicationId(final String applicationId)
     {
         this.applicationId = applicationId;
     }
 
+    /**
+     * <p>Getter for the field <code>apiKey</code>.</p>
+     *
+     * @return a {@link java.lang.String} object.
+     */
     public String getApiKey()
     {
         return apiKey;
     }
 
+    /**
+     * <p>Setter for the field <code>apiKey</code>.</p>
+     *
+     * @param apiKey a {@link java.lang.String} object.
+     */
     public void setApiKey(final String apiKey)
     {
         this.apiKey = apiKey;
@@ -48,11 +71,21 @@ private String getApiSecret()
         return apiSecret;
     }
 
+    /**
+     * <p>Setter for the field <code>apiSecret</code>.</p>
+     *
+     * @param apiSecret a {@link java.lang.String} object.
+     */
     public void setApiSecret(final String apiSecret)
     {
         this.apiSecret = apiSecret;
     }
 
+    /**
+     * <p>Getter for the field <code>authBaseUrl</code>.</p>
+     *
+     * @return a {@link java.lang.String} object.
+     */
     public String getAuthBaseUrl()
     {
         return authBaseUrl;
@@ -63,6 +96,11 @@ private void setAuthBaseUrl(final String authBaseUrl)
         this.authBaseUrl = authBaseUrl;
     }
 
+    /**
+     * <p>Getter for the field <code>controlBaseUrl</code>.</p>
+     *
+     * @return a {@link java.lang.String} object.
+     */
     public String getControlBaseUrl()
     {
         return controlBaseUrl;
@@ -79,6 +117,11 @@ private void loadDefaults()
         setControlBaseUrl("api.ws.sonos.com/control/api");
     }
 
+    /**
+     * <p>getAuthorizationHeader.</p>
+     *
+     * @return a {@link org.apache.http.Header} object.
+     */
     public Header getAuthorizationHeader()
     {
         final byte[] authBytes = String.join(":", getApiKey(), getApiSecret()).getBytes();

src/main/java/engineer/nightowl/sonos/api/domain/SonosAlbum.java

@@ -9,10 +9,21 @@ class SonosAlbum
     private URI imageUrl;
     private SonosMusicObjectId id;
 
+    /**
+     * <p>Constructor for SonosAlbum.</p>
+     */
     public SonosAlbum()
     {
     }
 
+    /**
+     * <p>Constructor for SonosAlbum.</p>
+     *
+     * @param name a {@link java.lang.String} object.
+     * @param artist a {@link engineer.nightowl.sonos.api.domain.SonosArtist} object.
+     * @param imageUrl a {@link java.net.URI} object.
+     * @param id a {@link engineer.nightowl.sonos.api.domain.SonosMusicObjectId} object.
+     */
     public SonosAlbum(final String name, final SonosArtist artist, final URI imageUrl, final SonosMusicObjectId id)
     {
         this.name = name;
@@ -21,46 +32,87 @@ public SonosAlbum(final String name, final SonosArtist artist, final URI imageUr
         this.id = id;
     }
 
+    /**
+     * <p>Getter for the field <code>name</code>.</p>
+     *
+     * @return a {@link java.lang.String} object.
+     */
     public String getName()
     {
         return name;
     }
 
+    /**
+     * <p>Setter for the field <code>name</code>.</p>
+     *
+     * @param name a {@link java.lang.String} object.
+     */
     public void setName(final String name)
     {
         this.name = name;
     }
 
+    /**
+     * <p>Getter for the field <code>artist</code>.</p>
+     *
+     * @return a {@link engineer.nightowl.sonos.api.domain.SonosArtist} object.
+     */
     public SonosArtist getArtist()
     {
         return artist;
     }
 
+    /**
+     * <p>Setter for the field <code>artist</code>.</p>
+     *
+     * @param artist a {@link engineer.nightowl.sonos.api.domain.SonosArtist} object.
+     */
     public void setArtist(final SonosArtist artist)
     {
         this.artist = artist;
     }
 
+    /**
+     * <p>Getter for the field <code>imageUrl</code>.</p>
+     *
+     * @return a {@link java.net.URI} object.
+     */
     public URI getImageUrl()
     {
         return imageUrl;
     }
 
+    /**
+     * <p>Setter for the field <code>imageUrl</code>.</p>
+     *
+     * @param imageUrl a {@link java.net.URI} object.
+     */
     public void setImageUrl(final URI imageUrl)
     {
         this.imageUrl = imageUrl;
     }
 
+    /**
+     * <p>Getter for the field <code>id</code>.</p>
+     *
+     * @return a {@link engineer.nightowl.sonos.api.domain.SonosMusicObjectId} object.
+     */
     public SonosMusicObjectId getId()
     {
         return id;
     }
 
+    /**
+     * <p>Setter for the field <code>id</code>.</p>
+     *
+     * @param id a {@link engineer.nightowl.sonos.api.domain.SonosMusicObjectId} object.
+     */
     public void setId(final SonosMusicObjectId id)
     {
         this.id = id;
     }
 
+    /** {@inheritDoc} */
     @Override
     public String toString()
     {