refactor(docs): improve JSDoc comments following oxlint jsdoc plugin

- Edit .oxlintrc.json to enable jsdoc plugin
- Added parameter and return type annotations in buildEnumObject, getType, fetchJsonLd, parseHydraDocumentation, and handleJson functions.

Signed-off-by: J3m5 <5523410+J3m5@users.noreply.github.com>

Author: J3m5

.oxlintrc.json

@@ -20,7 +20,8 @@
     "import",
     "eslint",
     "oxc",
-    "promise"
+    "promise",
+    "jsdoc"
   ],
   "rules": {
     "@typescript-eslint/no-empty-object-type": [

src/core/utils/buildEnumObject.ts

@@ -5,8 +5,8 @@ import { humanize } from "inflection";
  * The keys of the object are the humanized versions of the enum values,
  * and the values are the original enum values.
  *
- * @param enumArray - An array of enum values.
- * @returns An object mapping humanized enum names to their original values, or null if the input is empty.
+ * @param {any[] | undefined} enumArray - An array of enum values.
+ * @returns {Record<string, string | number> | null} An object mapping humanized enum names to their original values, or null if the input is empty.
  */
 export function buildEnumObject(
   enumArray: any[] | undefined,

src/core/utils/getType.ts

@@ -7,9 +7,9 @@ import type { FieldType } from "../Field.js";
  * If a format is provided, it will map certain formats (e.g., "int32", "int64") to "integer".
  * Otherwise, it will camelize the format string. If no format is provided, it returns the OpenAPI type.
  *
- * @param openApiType - The OpenAPI type string.
- * @param format - An optional format string.
- * @returns The mapped FieldType.
+ * @param {string} openApiType - The OpenAPI type string.
+ * @param {string} [format] - An optional format string.
+ * @returns {FieldType} The mapped FieldType.
  */
 export function getType(openApiType: string, format?: string): FieldType {
   if (format) {

src/hydra/fetchJsonLd.ts

@@ -19,6 +19,9 @@ interface ResponseDocument extends RemoteDocument {
 
 /**
  * Sends a JSON-LD request to the API.
+ * @param {string} url The URL to request.
+ * @param {RequestInitExtended} [options] Optional fetch options.
+ * @returns {Promise<ResponseDocument | EmptyResponseDocument>} The response document or an empty response document.
  */
 export default async function fetchJsonLd(
   url: string,

src/hydra/parseHydraDocumentation.ts

@@ -16,11 +16,19 @@ import type {
 
 /**
  * Extracts the short name of a resource.
+ * @param {string} url The resource URL.
+ * @param {string} entrypointUrl The API entrypoint URL.
+ * @returns {string} The short name of the resource.
  */
 function guessNameFromUrl(url: string, entrypointUrl: string): string {
   return url.slice(entrypointUrl.length + 1);
 }
 
+/**
+ * Gets the title or label from an ExpandedOperation object.
+ * @param {ExpandedOperation} obj The operation object.
+ * @returns {string} The title or label.
+ */
 function getTitleOrLabel(obj: ExpandedOperation): string {
   const a =
     obj["http://www.w3.org/2000/01/rdf-schema#label"] ??
@@ -36,6 +44,9 @@ function getTitleOrLabel(obj: ExpandedOperation): string {
 
 /**
  * Finds the description of the class with the given id.
+ * @param {ExpandedDoc[]} docs The expanded documentation array.
+ * @param {string} classToFind The class ID to find.
+ * @returns {ExpandedClass} The matching expanded class.
  */
 function findSupportedClass(
   docs: ExpandedDoc[],
@@ -87,6 +98,9 @@ export function getDocumentationUrlFromHeaders(headers: Headers): string {
 
 /**
  * Retrieves Hydra's entrypoint and API docs.
+ * @param {string} entrypointUrl The URL of the API entrypoint.
+ * @param {RequestInitExtended} [options] Optional fetch options.
+ * @returns {Promise<{ entrypointUrl: string; docsUrl: string; response: Response; entrypoint: Entrypoint[]; docs: ExpandedDoc[]; }>} An object containing entrypointUrl, docsUrl, response, entrypoint, and docs.
  */
 async function fetchEntrypointAndDocs(
   entrypointUrl: string,
@@ -98,6 +112,11 @@ async function fetchEntrypointAndDocs(
   entrypoint: Entrypoint[];
   docs: ExpandedDoc[];
 }> {
+  /**
+   * Loads a JSON-LD document from the given input.
+   * @param {string} input The URL or IRI to load.
+   * @returns {Promise<any>} The fetched JSON-LD response.
+   */
   async function documentLoader(input: string) {
     const response = await fetchJsonLd(input, options);
     if (!("body" in response)) {
@@ -154,6 +173,12 @@ async function fetchEntrypointAndDocs(
   }
 }
 
+/**
+ * Finds the related class for a property.
+ * @param {ExpandedDoc[]} docs The expanded documentation array.
+ * @param {ExpandedRdfProperty} property The property to find the related class for.
+ * @returns {ExpandedClass} The related expanded class.
+ */
 function findRelatedClass(
   docs: ExpandedDoc[],
   property: ExpandedRdfProperty,
@@ -213,6 +238,9 @@ function findRelatedClass(
 
 /**
  * Parses Hydra documentation and converts it to an intermediate representation.
+ * @param {string} entrypointUrl The API entrypoint URL.
+ * @param {RequestInitExtended} [options] Optional fetch options.
+ * @returns {Promise<{ api: Api; response: Response; status: number; }>} The parsed API, response, and status.
  */
 export default async function parseHydraDocumentation(
   entrypointUrl: string,
@@ -470,8 +498,12 @@ export default async function parseHydraDocumentation(
     });
 
     resource.parameters = [];
-    resource.getParameters = (): Promise<Parameter[]> =>
-      getParameters(resource, options);
+    resource.getParameters =
+      /**
+       * Gets the parameters for the resource.
+       * @returns {Promise<Parameter[]>} The parameters for the resource.
+       */
+      (): Promise<Parameter[]> => getParameters(resource, options);
 
     resources.push(resource);
   }

src/openapi3/handleJson.ts

@@ -20,10 +20,10 @@ import type {
  * Assigns relationships between resources based on their fields.
  * Sets the field's `embedded` or `reference` property depending on its type.
  *
- * @param resources - Array of Resource objects to process.
- * @returns The same array of resources with relationships assigned.
+ * @param {Resource[]} resources - Array of Resource objects to process.
+ * @returns {Resource[]} The same array of resources with relationships assigned.
  */
-function assignResourceRelationships(resources: Resource[]) {
+function assignResourceRelationships(resources: Resource[]): Resource[] {
   for (const resource of resources) {
     for (const field of resource.fields ?? []) {
       const name = camelize(field.name).replace(/Ids?$/, "");