docs: flesh out javadocs on client and controller

Signed-off-by: jonathan zollinger <jonathan.zollinger@outlook.com>

src/main/java/com/graqr/threshr/Threshr.java

@@ -26,7 +26,14 @@ public Threshr(@SuppressWarnings("ClassEscapesDefinedScope") ThreshrClient thres
         this.threshrClient = threshrClient;
     }
 
-
+    /**
+     * Query product summaries and their fulfillment options. See {@link ProductSummaryWithFulfillment}
+     *
+     * @param targetStore TargetStore object whose inventory is queried for product summaries
+     * @param tcin TCIN object for one or many product ID(s)
+     * @return List of product summaries, one for each ID in the tcin object.
+     * @throws ThreshrException if no product summaries are returned by the query
+     */
     @Get("/product/summary-with-fulfillment")
     @SingleResult
     public List<ProductSummaryWithFulfillment> fetchProductSummaries(TargetStore targetStore, Tcin tcin) throws ThreshrException {
@@ -35,12 +42,29 @@ public List<ProductSummaryWithFulfillment> fetchProductSummaries(TargetStore tar
                 .productSummaryWithFulfillmentList();
     }
 
+    /**
+     * Query product summaries and their fulfillment options. See {@link ProductSummaryWithFulfillment}
+     *
+     * @param targetStore TargetStore object whose inventory is queried for product summaries
+     * @param tcin single or many string values for product ID(s)
+     * @return List of product summaries, one for each ID in the tcin object.
+     * @throws ThreshrException if no product summaries are returned by the query
+     */
     @Get("/product/summary-with-fulfillment")
     @SingleResult
     public List<ProductSummaryWithFulfillment> fetchProductSummaries(TargetStore targetStore, String... tcin) throws ThreshrException {
         return fetchProductSummaries(targetStore, new Tcin(tcin));
     }
 
+    /**
+     * Queries the product details page for a given product at a given store.
+     *
+     * @param pricingStoreId 4-digit target store identifier
+     * @param storeId 4-digit target store identifier
+     * @param tcin Target's internal product id number. aka 'Target Catalog Identification Number'
+     * @return Product object matching the given query
+     * @throws ThreshrException if no Product matching given query is found
+     */
     @Get("/product/details")
     @SingleResult
     public Product fetchProductDetails(String pricingStoreId, String storeId, String tcin) throws ThreshrException {
@@ -49,12 +73,28 @@ public Product fetchProductDetails(String pricingStoreId, String storeId, String
                 .product();
     }
 
+    /**
+     * queries at most 5 stores within 100 miles of a given location
+     *
+     * @param place Either a zipcode or a city-state pair of strings. see {@link Place}.
+     * @return NearbyStores object with a list of store objects
+     * @throws ThreshrException if the returned value is null.
+     */
     @Get("/stores/locations-query")
     @SingleResult
     public NearbyStores getStores(Place place) throws ThreshrException {
         return getStores(5, 100, place);
     }
 
+    /**
+     * Queries stores relative to a given location
+     *
+     * @param place Either a zipcode or a city-state pair of strings. see {@link Place}.
+     * @param limit max store locations to include in returned NearbyStores object.
+     * @param within distance from given location to include in search.
+     * @return NearbyStores object with a list of store objects
+     * @throws ThreshrException if the returned value is null.
+     */
     @Get("/stores/locations-query")
     @SingleResult
     public NearbyStores getStores(int limit, int within, Place place) throws ThreshrException {

src/main/java/com/graqr/threshr/ThreshrClient.java

@@ -19,20 +19,9 @@
 
 /**
  * This is a Micronaut HttpClient which consumes the target corporation's api.
- * <p>
- * Uses the following environment variables:
- * <ul>
- *     <li><dfn id="KEY">THRESHR_KEY</dfn>: bearer token to authenticate against the redsky api.</li>
- *     <li><dfn id="VISITOR">THRESHR_VISITOR</dfn>: query value for member_id variable</li>
- *     <li><dfn id="CATEGORY">THRESHR_CATEGORY</dfn>: grocery category id.</li>
- *     <li><dfn id="CHANNEL">THRESHR_CHANNEL</dfn>: medium through which this api is exchanged. probably {@code WEB}</li>
- *     <li><dfn id="SEARCH:">THRESHR_NEW_SEARCH</dfn>: boolean value. probably {@code false}</li>
- *     <li><dfn id="OFFSET">THRESHR_OFFSET</dfn>: not entirely sure, but I think this is a starting position. seems to always be {@code 0}</li>
- *     <li><dfn id="PAGE">THRESHR_PAGE</dfn>: seems to always be a single character id related to category somehow.</li>
- *     <li><dfn id="PLATFORM">THRESHR_PLATFORM</dfn>: Where the api calls are made. probably {@code desktop}
- *     </li>
- * </ul>
- * </p>
+ *
+ * @author jonathan zollinger
+ * @since 0.0.11
  */
 @Client(id = "redsky-api")
 @Header(name = USER_AGENT, value = "Micronaut HTTP Client")
@@ -42,7 +31,6 @@ interface ThreshrClient {
     /**
      * Queries target's product summaries from of the given tcins at a given target store.
      * A product summary does not include pricing.
-     * Uses environment variables THRESHR_KEY and THRESHR_CHANNEL to authenticate.
      *
      * @param tcins       tcin ID's for products to query. see {@link Tcin#setTcins(String...)}
      * @param targetStore store from which the product summaries are to be queried.
@@ -58,6 +46,8 @@ HttpResponse<ProductSummaryRoot> getProductSummary(
             Tcin tcins);
 
     /**
+     * Get the pdp for the product with the given tcin from the given store.
+     *
      * @param tcin           tcin ID's for products to query
      * @param pricingStoreId I really don't know why this second iteration of storeId is needed.
      * @param storeId        store from which the product summaries are to be queried.