feat: update type and property descriptions

src/types/query.ts

@@ -1,3 +1,6 @@
+/**
+ * Represents the search options for querying.
+ */
 export interface XCQueryOption {
   /**
    * Group
@@ -252,14 +255,17 @@ export interface XCQueryOption {
    */
   smp?: number | string;
   /**
-   * Any other custom tags not in the API for compatibility
+   * Any other custom tags not in the API for compatibility.
    */
   [rest: string]: number | string | undefined;
 }
 
+/**
+ * Represents additional options for the wrapper.
+ */
 export interface AdditionalWrapperOption {
   /**
-   * Override the default BASE_URL
+   * Override the default BASE_URL.
    */
   baseUrl?: string;
 }

src/types/response.ts

@@ -1,113 +1,119 @@
+/**
+ * Represents the response object returned by the Xeno-Canto API.
+ */
 export interface XCResponse {
   /**
-   * the total number of recordings found for this query
+   * The total number of recordings found for this query.
    */
   numRecordings: number;
   /**
-   * the total number of species found for this query
+   * The total number of species found for this query.
    */
   numSpecies: number;
   /**
-   * the page number of the results page that is being displayed
+   * The page number of the results page that is being displayed.
    */
   page: number;
   /**
-   * the total number of pages available for this query
+   * The total number of pages available for this query.
    */
   numPages: number;
   /**
-   * an array of recording objects
+   * An array of recording objects.
    */
   recordings: XCRecording[];
   /**
-   * error type
+   * Error type, if any.
    */
   error?: string;
   /**
-   * error message
+   * Error message, if any.
    */
   message?: string;
 }
 
+/**
+ * Represents a recording entity from the Xeno-Canto API response's "recordings" array.
+ */
 export interface XCRecording {
   /**
-   * the catalogue number of the recording on xeno-canto
+   * The catalogue number of the recording on xeno-canto.
    */
   id: string;
   /**
-   * the generic name of the species
+   * The generic name of the species.
    */
   gen: string;
   /**
-   * the specific name (epithet) of the species
+   * The specific name (epithet) of the species.
    */
   sp: string;
   /**
-   * the subspecies name (subspecific epithet)
+   * The subspecies name (subspecific epithet).
    */
   ssp: string;
   /**
-   * the group to which the species belongs (birds, grasshoppers, bats)
+   * The group to which the species belongs (birds, grasshoppers, bats).
    */
   group: string;
   /**
-   * the English name of the species
+   * The English name of the species.
    */
   en: string;
   /**
-   * the name of the recordist
+   * The name of the recordist.
    */
   rec: string;
   /**
-   * the country where the recording was made
+   * The country where the recording was made.
    */
   cnt: string;
   /**
-   * the name of the locality
+   * The name of the locality.
    */
   loc: string;
   /**
-   * the latitude of the recording in decimal coordinates
+   * The latitude of the recording in decimal coordinates.
    */
   lat: string;
   /**
-   * the longitude of the recording in decimal coordinates
+   * The longitude of the recording in decimal coordinates.
    */
   lng: string;
   /**
-   * TODO: unknown usage
+   * Elevation (in meter).
    */
   alt: string;
   /**
-   * the sound type of the recording (combining both predefined terms such as 'call' or 'song' and additional free text options)
+   * The sound type of the recording (combining both predefined terms such as 'call' or 'song' and additional free text options).
    */
   type: string;
   /**
-   * the sex of the animal
+   * The sex of the animal.
    */
   sex: string;
   /**
-   * the life stage of the animal (adult, juvenile, etc.)
+   * The life stage of the animal (adult, juvenile, etc.).
    */
   stage: string;
   /**
-   * the recording method (field recording, in the hand, etc.)
+   * The recording method (field recording, in the hand, etc.).
    */
   method: string;
   /**
-   * the URL specifying the details of this recording
+   * The URL specifying the details of this recording.
    */
   url: string;
   /**
-   * the URL to the audio file
+   * The URL to the audio file.
    */
   file: string;
   /**
-   * the original file name of the audio file
+   * The original file name of the audio file.
    */
   fileName: string;
   /**
-   * an object with the URLs to the four versions of sonograms
+   * An object with the URLs to the four versions of sonograms.
    */
   sono: {
     small: string;
@@ -116,79 +122,79 @@ export interface XCRecording {
     full: string;
   };
   /**
-   * an object with the URLs to the three versions of oscillograms
+   * An object with the URLs to the three versions of oscillograms.
    */
   osci: {
     small: string;
     med: string;
     large: string;
   };
   /**
-   * the URL describing the license of this recording
+   * The URL describing the license of this recording.
    */
   lic: string;
   /**
-   * the current quality rating for the recording
+   * The current quality rating for the recording.
    */
   q: string;
   /**
-   * the length of the recording in minutes
+   * The length of the recording in minutes.
    */
   length: string;
   /**
-   * the time of day that the recording was made
+   * The time of day that the recording was made.
    */
   time: string;
   /**
-   * the date that the recording was made
+   * The date that the recording was made.
    */
   date: string;
   /**
-   * the date that the recording was uploaded to xeno-canto
+   * The date that the recording was uploaded to xeno-canto.
    */
   uploaded: string;
   /**
-   * an array with the identified background species in the recording
+   * An array with the identified background species in the recording.
    */
   also: string[];
   /**
-   * additional remarks by the recordist
+   * Additional remarks by the recordist.
    */
   rmk: string;
   /**
-   * indicates whether the recorded animal was seen
+   * Indicates whether the recorded animal was seen.
    */
   birdSeen: string;
   /**
-   * was the recorded animal seen
+   * Was the recorded animal seen.
    */
   animalSeen: string;
   /**
-   * was playback used to lure the animal
+   * Was playback used to lure the animal.
    */
   playbackUsed: string;
   /**
-   * temperature during recording (applicable to specific groups only)
+   * Temperature during recording (applicable to specific groups only).
    */
   temp: string;
   /**
-   * registration number of specimen (when collected)
+   * Registration number of specimen (when collected).
    */
   regnr: string;
   /**
-   * automatic (non-supervised) recording
+   * Automatic (non-supervised) recording.
    */
   auto: string;
   /**
-   * recording device used
+   * Recording device used.
    */
   dvc: string;
   /**
-   * microphone used
+   * Microphone used.
    */
   mic: string;
   /**
-   * sample rate
+   * Sample rate.
    */
   smp: number;
 }

src/utils/utils.ts

@@ -2,8 +2,7 @@ import { XCQueryOption } from "../types/query";
 import { XCRecording, XCResponse } from "../types/response";
 
 /**
- * Constructs a query URL by appending the provided query string to the base URL and
- * optionally including additional query options.
+ * Constructs a query URL by appending the provided query string to the base URL and optionally including additional query options.
  *
  * @param {string} baseUrl - The base URL to which the query string will be appended.
  * @param {string} query - The query string to be appended to the base URL.
@@ -41,10 +40,10 @@ export function constructQueryUrl(
 }
 
 /**
- * Converts an XCQueryOption object to a URL-encoded string.
+ * Converts an XCQueryOption object to a required URL string parameter format. For example: "grp:"birds" cnt:"United States" method:"field recording""
  *
  * @param {XCQueryOption} option - The XCQueryOption object to convert.
- * @return {string} The URL-encoded string representation of the XCQueryOption object.
+ * @return {string} The formatted string representation of the XCQueryOption object.
  */
 export function convertXCQueryOptionToString(option: XCQueryOption): string {
   if (!option) {