💡 more docstrings

core/src/controllers/search.ts

@@ -3,6 +3,11 @@ import { Request, Response } from 'express';
 
 import Person from '../models/Person';
 
+/**
+ * Searches for people/organizations based on a query string.
+ * @param req The request object.
+ * @param res The response object.
+ */
 export const search = async (req: Request, res: Response): Promise<void> => {
   if (!req.query.q) {
     res.status(400);

core/src/models/Organ.ts

@@ -3,7 +3,7 @@ import fs from 'fs';
 import fsPromises from 'fs/promises';
 
 /**
- * Represents a source for an organization. This could be a
+ * Represents a source for an organ. This could be a
  * website, a document, or any other kind of resource.
  */
 export class OrganSource {
@@ -15,29 +15,51 @@ export class OrganSource {
     this.url = url;
   }
 
+  /**
+   * Returns a JSON representation of the source.
+   * @returns The JSON representation of the source.
+   */
   public json (): Object {
     return {
       sid: this.sid,
       url: this.url,
     };
   }
 
+  /**
+   * Returns a string representation of the source.
+   * @returns The string representation of the source.
+   */
   public toString (): string {
     return `OrganSource#${this.sid}`;
   }
 
+  /**
+   * Updates the source in the database.
+   * @returns A promise that resolves when the source has been updated.
+   */
   public async update (): Promise<void> {
     const client = await pool.connect();
     await client.query('UPDATE organ_source SET url = $1 WHERE sid = $2', [this.url, this.sid]);
     client.release();
   };
 
+  /**
+   * Removes the source from the database.
+   * @returns A promise that resolves when the source has been removed.
+   */
   public async remove (): Promise<void> {
     const client = await pool.connect();
     await client.query('DELETE FROM organ_source WHERE sid = $1', [this.sid]);
     client.release();
   };
 
+  /**
+   * Creates a new source for an organ.
+   * @param organ The organ to create the source for.
+   * @param url The URL of the source.
+   * @returns A promise that resolves with the created source.
+   */
   public static async create (organ: Organ, url: string): Promise<OrganSource> {
     const client = await pool.connect();
     const res = await client.query('INSERT INTO organ_source (organ, url) VALUES ($1, $2) RETURNING sid', [organ.id, url]);
@@ -47,9 +69,9 @@ export class OrganSource {
 }
 
 /**
- * Represents a member of an organization. That member
+ * Represents a member of an organ. That member
  * doesn't have to be a natural person - they could themselves
- * be an organization, for example.
+ * be an organ, for example.
  */
 class Organ {
   public id: number;
@@ -60,44 +82,84 @@ class Organ {
     this.bio = bio;
   }
 
+  /**
+   * Returns a JSON representation of the organ.
+   * @returns The JSON representation of the organ.
+   */
   public json (): Object {
     return {
       id: this.id,
       bio: this.bio,
     };
   }
 
+  /**
+   * Returns a string representation of the organ.
+   * @returns The string representation of the organ.
+   */
   public toString (): string {
     return `Organ#${this.id}`;
   }
 
+  /**
+   * Adds a source to the organ.
+   * @param source The source to add.
+   * @returns A promise that resolves with the added source.
+   */
   public async add (source: string): Promise<OrganSource>;
   public async add (v: string): Promise<OrganSource> {
     if (typeof v === 'string') return OrganSource.create(this, v);
     throw new Error('Invalid addition type');
   }
 
+  /**
+   * Updates the organ in the database.
+   * @returns A promise that resolves when the organ has been updated.
+   */
   public async update (): Promise<void>;
+  /**
+   * Updates a source for the organ.
+   * @param source The source to update.
+   * @returns A promise that resolves when the source has been updated.
+   */
   public async update (source: OrganSource): Promise<void>;
   public update (v?: OrganSource): Promise<void> {
     if (v instanceof OrganSource) return v.update();
     return fsPromises.writeFile(`${process.env.DATA_DIR}/${this.id}.md`, this.bio);
   }
 
+  /**
+   * Removes a source from the organ.
+   * @param source The source to remove.
+   * @returns A promise that resolves when the source has been removed.
+   */
   public async remove (source: OrganSource): Promise<void>;
   public remove (v: OrganSource): Promise<void> {
     if (v instanceof OrganSource) return v.remove();
     throw new Error('Invalid removal type');
   }
 
+  /**
+   * Returns all sources for the organ.
+   * @returns A promise that resolves with all sources for the organ.
+   */
   public async sources (): Promise<OrganSource[]> {
     const client = await pool.connect();
     const res = await client.query('SELECT sid, url FROM organ_source WHERE organ = $1', [this.id]);
     client.release();
     return res.rows.map(row => new OrganSource(+row.sid, row.url));
   }
 
+  /**
+   * Creates a new organ.
+   * @returns A promise that resolves with the created organ.
+   */
   public static async create (): Promise<Organ>;
+  /**
+   * Creates a new organ with a bio.
+   * @param bio The bio of the organ.
+   * @returns A promise that resolves with the created organ.
+   */
   public static async create (bio: string): Promise<Organ>;
   public static async create (v?: string): Promise<Organ> {
     const client = await pool.connect();
@@ -108,6 +170,11 @@ class Organ {
     return new Organ(oid, v||'');
   }
 
+  /**
+   * Finds an organ by its ID.
+   * @param id The ID of the organ to find.
+   * @returns A promise that resolves with the found organ, or null if it doesn't exist.
+   */
   public static async get (id: number): Promise<Organ|null> {
     const client = await pool.connect();
     const res = await client.query('SELECT * FROM organ WHERE oid = $1', [id]);