Fix Javadoc

Author: laurentpellegrino

src/main/java/co/ipregistry/api/client/IpregistryConfig.java

@@ -22,39 +22,74 @@
 
 
 /**
- * Configuration options for {@link IpregistryClient}.
+ * Configuration settings for the Ipregistry API client.
+ * <p>
+ * This class provides configuration options for customizing the behavior of the
+ * {@link IpregistryClient}, including API authentication, endpoint URLs, and
+ * network timeout settings. Use the builder pattern to create instances with
+ * custom configuration values.
+ * </p>
+ * <p>
+ * Instances are created using the Builder pattern. The class uses Lombok's {@code @Builder} 
+ * annotation to generate a builder with proper constructor handling for required and optional fields.
+ * </p>
  */
 @Builder
 @Getter
 public class IpregistryConfig {
 
     /**
-     * The IpregistryClient API key used to authenticate calls.
+     * Creates a new IpregistryConfig with the specified parameters.
+     * This constructor is used internally by the Builder pattern.
+     *
+     * @param apiKey the API key for authentication
+     * @param baseUrl the base URL for the API
+     * @param connectionKeepAlive connection keep-alive timeout
+     * @param connectionTimeout connection timeout
+     * @param socketTimeout socket timeout
+     */
+    public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive, int connectionTimeout, int socketTimeout) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.connectionKeepAlive = connectionKeepAlive;
+        this.connectionTimeout = connectionTimeout;
+        this.socketTimeout = socketTimeout;
+    }
+
+    /**
+     * The API key used to authenticate requests to the Ipregistry API.
+     * This key is required and must be obtained from your Ipregistry account dashboard.
      */
     @NonNull
     private final String apiKey;
 
     /**
-     * The IpregistryClient API endpoint URL.
+     * The base URL for the Ipregistry API endpoint.
+     * Defaults to "https://api.ipregistry.co" but can be customized for testing or private deployments.
      */
     @Builder.Default
     private String baseUrl = "https://api.ipregistry.co";
 
     /**
-     * The maximum amount of time that a connection to the server should be kept alive. This is useful for reducing the number of connections that need to be created, which can improve performance and reduce bandwidth usage.
+     * The maximum time in milliseconds that HTTP connections should be kept alive for reuse.
+     * Keeping connections alive reduces overhead by reusing existing connections for multiple requests.
+     * Defaults to 15 minutes (900,000 milliseconds).
      */
     @Builder.Default
     private final int connectionKeepAlive = 15 * 60 * 1000;
 
     /**
-     * The time to wait in milliseconds until a connection is established.
+     * The maximum time in milliseconds to wait when establishing a connection to the server.
+     * If a connection cannot be established within this time, the request will fail.
+     * Defaults to 15 seconds (15,000 milliseconds).
      */
     @Builder.Default
     private final int connectionTimeout = 15000;
 
     /**
-     * The time to wait for data in milliseconds.
-     * Said differently, the maximum period inactivity of between two consecutive data packets.
+     * The maximum time in milliseconds to wait for data between consecutive data packets.
+     * This is the socket read timeout, which determines how long to wait for the server
+     * to send data after the connection is established. Defaults to 15 seconds (15,000 milliseconds).
      */
     @Builder.Default
     private final int socketTimeout = 15000;

src/main/java/co/ipregistry/api/client/model/Carrier.java

@@ -24,18 +24,35 @@
 
 /**
  * Wraps mobile carrier data (name, MCC, MNC) associated with an IP address.
+ * This class provides information about the mobile network operator that owns
+ * a mobile IP address, including the carrier name and network codes.
  */
 @AllArgsConstructor
 @Data
-@NoArgsConstructor
 public final class Carrier {
 
+    /**
+     * Creates a new Carrier instance with default values.
+     * This constructor is primarily used for JSON deserialization and object initialization.
+     */
+    public Carrier() {
+    }
+
+    /**
+     * The name of the mobile carrier/operator.
+     */
     @JsonProperty("name")
     private String name;
 
+    /**
+     * Mobile Country Code (MCC) - a 3-digit code identifying the country of the mobile network.
+     */
     @JsonProperty("mcc")
     private String mcc;
 
+    /**
+     * Mobile Network Code (MNC) - a 2-3 digit code identifying the mobile network within a country.
+     */
     @JsonProperty("mnc")
     private String mnc;
 

src/main/java/co/ipregistry/api/client/model/Company.java

@@ -24,18 +24,35 @@
 
 /**
  * Wraps company data associated with an IP address.
+ * Contains information about the organization that owns or operates
+ * the IP address, including company name, domain, and business type.
  */
 @AllArgsConstructor
 @Data
-@NoArgsConstructor
 public class Company {
 
+    /**
+     * Creates a new Company instance with default values.
+     * This constructor is primarily used for JSON deserialization and object initialization.
+     */
+    public Company() {
+    }
+
+    /**
+     * The name of the company or organization.
+     */
     @JsonProperty("name")
     private String name;
 
+    /**
+     * The primary domain name associated with the company.
+     */
     @JsonProperty("domain")
     private String domain;
 
+    /**
+     * The type/category of the company (e.g., business, education, government).
+     */
     @JsonProperty("type")
     private CompanyType type;
 

src/main/java/co/ipregistry/api/client/model/Connection.java

@@ -24,24 +24,47 @@
 
 /**
  * Wraps connection data associated with an IP address.
+ * Contains network infrastructure information including ASN, organization,
+ * routing details, and connection type classification.
  */
 @AllArgsConstructor
 @Data
-@NoArgsConstructor
 public class Connection {
 
+    /**
+     * Creates a new Connection instance with default values.
+     * This constructor is primarily used for JSON deserialization and object initialization.
+     */
+    public Connection() {
+    }
+
+    /**
+     * The Autonomous System Number (ASN) that manages the IP address.
+     */
     @JsonProperty("asn")
     private Long asn;
 
+    /**
+     * The primary domain name associated with the organization.
+     */
     @JsonProperty("domain")
     private String domain;
 
+    /**
+     * The name of the organization or ISP that owns the IP address.
+     */
     @JsonProperty("organization")
     private String organization;
 
+    /**
+     * The IP route or subnet in CIDR notation.
+     */
     @JsonProperty("route")
     private String route;
 
+    /**
+     * The classification of the connection type (e.g., ISP, business, hosting).
+     */
     @JsonProperty("type")
     private ConnectionType type;
 

src/main/java/co/ipregistry/api/client/model/Continent.java

@@ -24,17 +24,36 @@
 
 
 /**
- * Wraps continent data associated with an IP address.
+ * Represents continent information associated with an IP address location.
+ * <p>
+ * This class contains basic continent identification data, including the continent
+ * code and name. It provides geographical context at the continental level for
+ * IP address geolocation results.
+ * </p>
  */
 @AllArgsConstructor
 @Builder
 @Data
-@NoArgsConstructor
 public class Continent {
 
+    /**
+     * Creates a new Continent instance with default values.
+     * This constructor is used for JSON deserialization and the Builder pattern.
+     */
+    public Continent() {
+    }
+
+    /**
+     * The two-letter continent code (e.g., "NA" for North America, "EU" for Europe, "AS" for Asia).
+     * This follows standard continent abbreviation conventions used in geographical data.
+     */
     @JsonProperty("code")
     private String code;
 
+    /**
+     * The full English name of the continent (e.g., "North America", "Europe", "Asia").
+     * Provides the human-readable name for the continent.
+     */
     @JsonProperty("name")
     private String name;
 

src/main/java/co/ipregistry/api/client/model/Country.java

@@ -25,43 +25,99 @@
 
 
 /**
- * Wraps country data associated with an IP address.
+ * Represents country information associated with an IP address location.
+ * <p>
+ * This class contains comprehensive country-level data including geographical,
+ * demographic, political, and administrative information. It provides details
+ * about the country where an IP address is located, including physical characteristics,
+ * population statistics, governmental information, and cultural attributes.
+ * </p>
  */
 @AllArgsConstructor
 @Data
-@NoArgsConstructor
 public class Country {
 
+    /**
+     * Creates a new Country instance with default values.
+     * This constructor is primarily used for JSON deserialization and object initialization.
+     */
+    public Country() {
+    }
+
+    /**
+     * The total land area of the country in square kilometers.
+     * Represents the geographical size of the country's territory.
+     */
     @JsonProperty("area")
     private double area;
 
+    /**
+     * List of ISO 3166-1 alpha-2 country codes for countries that share land borders.
+     * Contains two-letter country codes (e.g., ["US", "MX"]) for neighboring countries.
+     */
     @JsonProperty("borders")
     private List<String> borders;
 
+    /**
+     * The international dialing code for the country (e.g., "+1", "+44", "+33").
+     * Used for making international phone calls to this country.
+     */
     @JsonProperty("calling_code")
     private String callingCode;
 
+    /**
+     * The name of the country's capital city.
+     * May be null for countries without a designated capital.
+     */
     @JsonProperty("capital")
     private String capital;
 
+    /**
+     * The ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "FR").
+     * This is the standard two-letter country code used internationally.
+     */
     @JsonProperty("code")
     private String code;
 
+    /**
+     * The official English name of the country (e.g., "United States", "United Kingdom").
+     * Provides the commonly used English name for the country.
+     */
     @JsonProperty("name")
     private String name;
 
+    /**
+     * The total population of the country.
+     * Represents the estimated number of inhabitants in the country.
+     */
     @JsonProperty("population")
     private int population;
 
+    /**
+     * The population density in people per square kilometer.
+     * Calculated as population divided by total area, indicating how crowded the country is.
+     */
     @JsonProperty("population_density")
     private double populationDensity;
 
+    /**
+     * Information about the country's flag including colors, design, and emoji representation.
+     * Contains visual and symbolic information about the national flag.
+     */
     @JsonProperty("flag")
     private Flag flag;
 
+    /**
+     * List of languages officially spoken or commonly used in the country.
+     * Contains language information including codes, names, and native representations.
+     */
     @JsonProperty("languages")
     private List<Language> languages;
 
+    /**
+     * The country code top-level domain (ccTLD) for the country (e.g., ".us", ".uk", ".fr").
+     * This is the Internet domain extension assigned to the country.
+     */
     @JsonProperty("tld")
     private String tld;