Corrected JavaDoc omissions

a2d6685f · Christopher Bohn · d4a496fc · a2d6685f · a2d6685f · a2d6685f
Commit a2d6685f authored Nov 09, 2021 by Christopher Bohn 🤔
--- a/README.md
+++ b/README.md
-# JSON Connections for Files and REST APIs
+# OpenWeather Connector

-## With an enclosing connector for OpenWeather data
-
-REpresentational State Transfer APIs (also known as REST APIs, RESTful APIs, or
-RESTful web services) are a mechanism to request data from and send data to
-remote servers without maintaining active, stateful connections over a
-possibly-unreliable network. The
-`edu.unl.cse.soft160.json_connections.connection.RestConnection` class is
-sufficient to request data from a RESTful service.
-
-The `edu.unl.cse.soft160.json_connections.connection.FileConnection` class
-offers the same interface for requesting data, except that the data will be
-found on the local file system. `FileConnection` can also save data to a file
-which can be used to save data retrieved from a server using `RestConnection`
-to be used later.
-
-The `edu.unl.cse.soft160.json_connections.connector.OpenWeatherConnector` class
-provides a wrapper for `RestConnection` and `FileConnection` to simplify client
-code that uses data from [OpenWeathermap.org](https://openweathermap.org).
-
-### Instructions to use `OpenWeatherConnector`
+## Instructions to use `OpenWeatherConnector`

 1. Obtain an API key from OpenWeathermap.org by
   [signing up](https://home.openweathermap.org/users/sign_up) for a free
@@ -41,20 +22,22 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
     this.
   - Do NOT place your API key in `apikeys.json-TEMPLATE`, or you will cause
     your API key to be present in your repository.
-3. When creating an `OpenWeatherConnector` object, if it should connect to the
-   local file system, then use the single-argument constructor, using "weather",
-   "onecall", "forecast", or "air_pollution" as the argument (or another
-   subdirectory of `src/main/resources/` that is named after one of the data 
-   sets provided by the
-   [OpenWeathermap.org API](https://openweathermap.org/api)).
+3. You may wish to review `edu.unl.cse.soft160.json_connections.Demonstration`
+   to see example uses of `OpenWeatherConnector`.
 4. When creating an `OpenWeatherConnector` object, if it should connect to the
+   local file system, then use the single-argument constructor, using "weather",
+   "onecall", "forecast", "air_pollution", "air_pollution/history", or
+   "air_pollution/forecast" as the argument (or another subdirectory of
+   `src/main/resources/` that is named after one of the data sets provided by
+   the [OpenWeather API](https://openweathermap.org/api)).
+5. When creating an `OpenWeatherConnector` object, if it should connect to the
   OpenWeathermap.org RESTful service, use the two-argument constructor. The
   first argument needs to be one of the data sets provided by the
-   [OpenWeathermap.org API](https://openweathermap.org/api), and the second
+   [OpenWeather API](https://openweathermap.org/api), and the second
   argument needs to be the user's API key. Do not hard-code an API key.
   Instead, Call `RestConnection.getApiKey("openweathermap")` to obtain the
   API key from `apikeys.json` or prompt the user to enter their API key.
-5. You *must* invoke an `OpenWeatherConnector` object's `retrieveData(String)`
+6. You *must* invoke an `OpenWeatherConnector` object's `retrieveData(String)`
   method before invoking any of its other non-constructor methods to obtain
   the data that the other methods will use. You *may* make additional calls to
   `retrieveData(String)` to replace the data with other data.
@@ -64,21 +47,70 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
   - If the `OpenWeatherConnector` instance is connected to OpenWeathermap.org
     RESTful service, then the argument is the query string to be sent to
     the RESTful service. See the
-     [OpenWeathermap.org API specification](https://openweathermap.org/api) for
-     details.
-     - [*"weather"*](https://openweathermap.org/current), the current weather
-       data set
-     - [*"onecall"*](https://openweathermap.org/api/one-call-api), the "One
-       Call API" data set
-     - [*forecast*](https://openweathermap.org/forecast5), the 5-day/3-hour
-       forecast data set
-     - [*air_pollution*](https://openweathermap.org/api/air-pollution), the air
-       quality and pollution data set
-       - Includes *air_pollution/forecast* and *air_pollution/history*
-6. The remaining `OpenWeatherConnector` methods provide typed values for the
+     [OpenWeather API specification](https://openweathermap.org/api) for
+     details. 
+     - Pay particular attention to option to specify the system of measurements
+       in the query, and which data are available only in one unit of measure.
+     - Here are links to the query details for specific data sets:
+       - [*"weather"*](https://openweathermap.org/current), the current weather
+         data set
+       - [*"onecall"*](https://openweathermap.org/api/one-call-api), the "One
+         Call API" data set
+       - [*forecast*](https://openweathermap.org/forecast5), the 5-day/3-hour
+         forecast data set
+       - [*air_pollution*](https://openweathermap.org/api/air-pollution), the air
+         quality and pollution data set
+         - Includes *air_pollution/forecast* and *air_pollution/history*
+7. The remaining `OpenWeatherConnector` methods provide typed values for the
   JSON fields in the data loaded by `retrieveData(String)`.

-### Limitations
+## Use in Your Project
+
+### JavaDoc
+
+You can generate the JavaDoc pages for publicly-accessible elements by invoking
+the `javadoc:javadoc` Maven target from your IDE or from the command line:
+```
+mvn javadoc:javadoc
+```
+Open the file `target/site/apidocs/index.html` in your web browser to use the
+JavaDoc pages.
+
+### Copying files into your project
+
+If you copy the classes and interface from this project into your own, be sure
+that:
+- You copy the fields into the same directories, *i.e.*:
+  - `src/main/java/edu/unl/cse/soft160/json_connections/connection/Connection.java`
+  - `src/main/java/edu/unl/cse/soft160/json_connections/connection/FileConnection.java`
+  - `src/main/java/edu/unl/cse/soft160/json_connections/connection/RestConnection.java`
+  - `src/main/java/edu/unl/cse/soft160/json_connections/connector/OpenWeatherConnector.java`
+  - `src/main/resources/apikeys-TEMPLATE.json`
+  - `src/main/resources/.gitignore` (this file prevents `apikeys.json` from
+     being committed to your repository)
+- Your `pom.xml` file specifies the appropriate plugins and dependencies
+  - Your `pom.xml` file specifies Java version 11 or later
+    ```xml
+    <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.8.1</version>
+        <configuration>
+           <source>11</source>
+           <target>11</target>
+        </configuration>
+    </plugin>
+    ```
+  - Your `pom.xml` file includes a dependency for
+    [JSON.simple](https://mvnrepository.com/artifact/com.googlecode.json-simple/json-simple)
+    ```xml
+    <dependency>
+        <groupId>com.googlecode.json-simple</groupId>
+        <artifactId>json-simple</artifactId>
+        <version>1.1.1</version>
+     </dependency>
+    ```
+
+## Limitations

 - `OpenWeatherConnector` only supports the free, no-cost APIs provided by
  [OpenWeathermap.org](https://openweathermap.org). We do not have plans to
@@ -101,22 +133,21 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
  into question the assumption that a 3-hour value will be reported when rain
  has fallen for more than an hour (or even more than three hours)

-### Use in Your Project
-
-#### JavaDoc
+## JSON Connections for Files and REST APIs

-You can generate the JavaDoc pages for publicly-accessible elements by invoking
-the `javadoc:javadoc` Maven target from your IDE or from the command line:
-```
-mvn javadoc:javadoc
-```
-Open the file `target/site/apidocs/index.html` in your web browser to use the
-JavaDoc pages.
+REpresentational State Transfer APIs (also known as REST APIs, RESTful APIs, or
+RESTful web services) are a mechanism to request data from and send data to
+remote servers without maintaining active, stateful connections over a
+possibly-unreliable network. The
+`edu.unl.cse.soft160.json_connections.connection.RestConnection` class is
+sufficient to request data from a RESTful service.

-#### Maven notes
+The `edu.unl.cse.soft160.json_connections.connection.FileConnection` class
+offers the same interface for requesting data, except that the data will be
+found on the local file system. `FileConnection` can also save data to a file
+which can be used to save data retrieved from a server using `RestConnection`
+to be used later.

-If you copy the classes and interface from this project into your own, be sure
-that:
- Your `pom.xml` file specifies Java version 11 or later
- Your `pom.xml` file includes a dependency for
-  [JSON.simple](https://mvnrepository.com/artifact/com.googlecode.json-simple/json-simple)
\ No newline at end of file
+The `edu.unl.cse.soft160.json_connections.connector.OpenWeatherConnector` class
+provides a wrapper for `RestConnection` and `FileConnection` to simplify client
+code that uses data from [OpenWeathermap.org](https://openweathermap.org).
\ No newline at end of file
--- a/src/main/java/edu/unl/cse/soft160/json_connections/connector/OpenWeatherConnector.java
+++ b/src/main/java/edu/unl/cse/soft160/json_connections/connector/OpenWeatherConnector.java
@@ -56,7 +56,11 @@ public class OpenWeatherConnector {
    }

    /**
-     * <p>Air Quality Indices reported in OpenWeather air pollution reports.</p>
+     * <p>Air Quality Indices reported in OpenWeather air pollution reports. Note that while openweathermap.org refers
+     * to the Air Quality Indices on a scale of Good (1) to Very Poor (5), the CAQI Air Quality Index report refers to
+     * the Air Quality Indices as a level of pollutants on a scale of Very Low (1) to Very High (5). Numerically they
+     * are equivalent but the English-language meaning is different. This enumerated type uses the CAQI
+     * nomenclature.</p>
     *
     * <p>(n.b., {@link AirQuality#UNKNOWN_AIR_QUALITY} is a catch-all when no air quality data is present.)</p>
     *
@@ -342,8 +346,6 @@ public class OpenWeatherConnector {
     * <p>Available for all datasets.</p>
     *
     * @return location's latitude
-     * @see #getLongitude()
-     * @see #getTimestamp()
     */
    public double getLatitude() {
        checkForDataReadiness(null);
@@ -363,8 +365,6 @@ public class OpenWeatherConnector {
     * <p>Available for all datasets.</p>
     *
     * @return location's longitude
-     * @see #getLatitude()
-     * @see #getTimestamp()
     */
    public double getLongitude() {
        checkForDataReadiness(null);
@@ -385,8 +385,6 @@ public class OpenWeatherConnector {
     * <p>Available for all datasets with data for the present.</p>
     *
     * @return timestamp for the weather observations
-     * @see #getLatitude()
-     * @see #getLongitude()
     */
    public Date getTimestamp() {
        checkForDataReadiness(null);
@@ -415,7 +413,7 @@ public class OpenWeatherConnector {
     * <p>Provides all dates and times for reports with multiple timestamps.</p>
     * <p>Available for all datasets with data in the past or the future.</p>
     *
-     * @throws IllegalStateException if no data has been retrieved using {@link #retrieveData(String)}
+     * @return list of timestamps for the weather observations
     */
    public List<Date> getTimestamps() {
        checkForDataReadiness(null);
@@ -433,7 +431,7 @@ public class OpenWeatherConnector {
     * <p>Available for all datasets with data in the past or the future.</p>
     *
     * @param listName the name of the list whose timestamps are of interest
-     * @throws IllegalStateException if no data has been retrieved using {@link #retrieveData(String)}
+     * @return list of timestamps for the weather observations
     */
    public List<Date> getTimestamps(String listName) {
        checkForDataReadiness(null);
@@ -1102,6 +1100,7 @@ public class OpenWeatherConnector {
     * timestamp.</p>
     * <p>Available for the "onecall" (hourly only) dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted rainfall
     * @return the forecasted one-hour rainfall total, or 0.0 if rain volume is not in the forecast
     */
    public double getOneHourRainfall(Date timestamp) {
@@ -1125,6 +1124,7 @@ public class OpenWeatherConnector {
     * timestamp.</p>
     * <p>Available for the "forecast" dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted rainfall
     * @return the forecasted three-hour rainfall total, or 0.0 if rain volume is not in the forecast
     */
    public double getThreeHourRainfall(Date timestamp) {
@@ -1149,6 +1149,7 @@ public class OpenWeatherConnector {
     * timestamp.</p>
     * <p>Available for the "onecall" (hourly only) dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted snowfall
     * @return the forecasted one-hour rainfall total, or 0.0 if rain volume is not in the forecast
     */
    public double getOneHourSnowfall(Date timestamp) {
@@ -1172,6 +1173,7 @@ public class OpenWeatherConnector {
     * timestamp.</p>
     * <p>Available for the "forecast" dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted snowfall
     * @return the forecasted three-hour snowfall total, or 0.0 if snow volume is not in the forecast
     */
    public double getThreeHourSnowfall(Date timestamp) {
@@ -1185,6 +1187,7 @@ public class OpenWeatherConnector {
     * snow.</p>
     * <p>Available for the "onecall" dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted precipitation
     * @return the forecasted precipitation total, or 0.0 if precipitation volume is not in the forecast
     */
    public double getMinutelyPrecipitation(Date timestamp) {
@@ -1197,6 +1200,7 @@ public class OpenWeatherConnector {
     * API specification, this appears to be a daily total.</p>
     * <p>Available for the "onecall" dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted rainfall
     * @return the forecasted rain total, or 0.0 if precipitation volume is not in the forecast
     */
    public double getDailyRainfall(Date timestamp) {
@@ -1209,6 +1213,7 @@ public class OpenWeatherConnector {
     * API specification, this appears to be a daily total.</p>
     * <p>Available for the "onecall" dataset.</p>
     *
+     * @param timestamp the timestamp for the forecasted snowfall
     * @return the forecasted snow total, or 0.0 if precipitation volume is not in the forecast
     */
    public double getDailySnowfall(Date timestamp) {

--- a/src/test/java/edu/unl/cse/soft160/json_connections/ExceptionsTest.java
+++ b/src/test/java/edu/unl/cse/soft160/json_connections/ExceptionsTest.java