docs(banners): add banner docs (#470)

src/controller/banner-controller.ts

@@ -19,9 +19,7 @@
  */
 
 /**
- * This is the module page of banner-controller.
- *
- * @module banners
+ * @module Banners
  */
 
 import { Response } from 'express';
@@ -37,6 +35,9 @@ import FileService from '../service/file-service';
 import { BANNER_IMAGE_LOCATION } from '../files/storage';
 import { parseRequestPagination } from '../helpers/pagination';
 
+/**
+ * Controller for managing all routes related to the `banner` entity.
+ */
 export default class BannerController extends BaseController {
   private logger: Logger = log4js.getLogger('BannerController');
 

src/controller/request/banner-request.ts

@@ -19,12 +19,11 @@
  */
 
 /**
- * This is the module page of the banner-request.
- *
- * @module banners
+ * @module Banners
  */
 
 /**
+ * API Request for creating a `banner` entity.
  * @typedef {object} BannerRequest
  * @property {string} name - Name/label of the banner
  * @property {number} duration - How long the banner should be shown (in seconds)

src/controller/response/banner-response.ts

@@ -19,15 +19,14 @@
  */
 
 /**
- * This is the module page of the banner-response.
- *
- * @module banners
+ * @module Banners
  */
 
 import BaseResponse from './base-response';
 import { PaginationResult } from '../../helpers/pagination';
 
 /**
+ * API Response for the `banner` entity.
  * @typedef {allOf|BaseResponse} BannerResponse
  * @property {string} name.required - Name/label of the banner
  * @property {string} image - Location of the image
@@ -46,6 +45,7 @@ export interface BannerResponse extends BaseResponse {
 }
 
 /**
+ * Paginated API Response for the `banner` entity.
  * @typedef {object} PaginatedBannerResponse
  * @property {PaginationResult} _pagination - Pagination metadata
  * @property {Array<BannerResponse>} records - Returned banners

src/entity/banner.ts

@@ -19,9 +19,16 @@
  */
 
 /**
- * This is the module page of banner.
+ * `banners` are used to manage promotional material within SudoSOS, commonly displayed on the point of sale.
+ * They can be configured with a duration, activation status, and start/end dates to control their visibility.
  *
- * @module banners
+ * ### Usage
+ * - Banners can be created, updated, or deleted by admins.
+ * - Active banners can be retrieved without authentication.
+ *
+ * For API interactions, refer to the [Swagger Documentation](https://sudosos.gewis.nl/api/api-docs/#/banners).
+ *
+ * @module Banners
  * @mergeTarget
  */
 
@@ -32,6 +39,7 @@ import BaseEntity from './base-entity';
 import BannerImage from './file/banner-image';
 
 /**
+ * TypeORM entity for the `banners` table.
  * @typedef {BaseEntity} Banner
  * @property {string} name - Name/label of the banner.
  * @property {integer} duration - How long the banner should be shown (in seconds).

src/entity/file/banner-image.ts

@@ -19,15 +19,15 @@
  */
 
 /**
- * This is the module page of banner-image.
- *
- * @module banners
+ * @module Banners
  */
 
 import { Entity } from 'typeorm';
 import BaseFile from './base-file';
 
 /**
+ * TypeORM entity for banner images.
+ * Note that the image itself is stored in the file system, but the table is used to store the location of the image.
  * @typedef {BaseFile} BannerImage
  */
 @Entity()

src/service/banner-service.ts

@@ -19,9 +19,7 @@
  */
 
 /**
- * This is the module page of the banner-service.
- *
- * @module banners
+ * @module Banners
  */
 
 import { FindManyOptions } from 'typeorm';
@@ -32,11 +30,17 @@ import QueryFilter, { FilterMapping } from '../helpers/query-filter';
 import FileService from './file-service';
 import { PaginationParameters } from '../helpers/pagination';
 
+/**
+ * Filter parameters for the `banner` entity.
+ */
 export interface BannerFilterParameters {
   bannerId?: number,
   active?: boolean,
 }
 
+/**
+ * Service class for the `banner` entity,
+ */
 export default class BannerService {
   /**
    * Verifies whether the banner request translates to a valid banner object