Second part of the action comment refactoring

ref #39

src/models/actions/CreateAddress.ts

@@ -1,16 +1,19 @@
 import { IsNotEmpty, IsOptional, IsPostalCode, IsString } from 'class-validator';
 import { Address } from '../entities/Address';
 
+/**
+ * This classed is used to create a new Address entity from a json body (post request).
+ */
 export class CreateAddress {
     /**
-   * The address's description.
-   */
+     * The newaddress's description.
+     */
     @IsString()
     @IsOptional()
     description?: string;
 
     /**
-     * The address's first line.
+     * The new address's first line.
      * Containing the street and house number.
      */
     @IsString()
@@ -18,7 +21,7 @@ export class CreateAddress {
     address1: string;
 
     /**
-     * The address's second line.
+     * The new address's second line.
      * Containing optional information.
      */
     @IsString()
@@ -26,7 +29,9 @@ export class CreateAddress {
     address2?: string;
 
     /**
-     * The address's postal code.
+     * The new address's postal code.
+     * This will get checked against the postal code syntax for the configured country.
+     * TODO: Implement the config option. 
      */
     @IsString()
     @IsNotEmpty()
@@ -34,21 +39,21 @@ export class CreateAddress {
     postalcode: string;
 
     /**
-     * The address's city.
+     * The new address's city.
      */
     @IsString()
     @IsNotEmpty()
     city: string;
 
     /**
-     * The address's country.
+     * The new address's country.
      */
     @IsString()
     @IsNotEmpty()
     country: string;
 
     /**
-     * Creates a Address object based on this.
+     * Creates a new Address entity from this.
      */
     public toAddress(): Address {
         let newAddress: Address = new Address();

src/models/actions/CreateAuth.ts

@@ -8,7 +8,7 @@ import { User } from '../entities/User';
 import { Auth } from '../responses/ResponseAuth';
 
 /**
- * This class is used to create auth credentials.
+ * This class is used to create auth credentials based on user credentials provided in a json body (post request).
  * To be a little bit more exact: Is takes in a username/email + password and creates a new access and refresh token for the user.
  * It of course checks for user existance, password validity and so on.
  */

src/models/actions/CreateGroupContact.ts

@@ -5,32 +5,34 @@ import { AddressNotFoundError, AddressWrongTypeError } from '../../errors/Addres
 import { Address } from '../entities/Address';
 import { GroupContact } from '../entities/GroupContact';
 
+/**
+ * This classed is used to create a new Group entity from a json body (post request).
+ */
 export class CreateGroupContact {
     /**
-       * The contact's first name.
-       */
+     * The new contact's first name.
+     */
     @IsNotEmpty()
     @IsString()
     firstname: string;
 
     /**
-     * The contact's middle name.
-     * Optional
+     * The new contact's middle name.
      */
     @IsOptional()
     @IsString()
     middlename?: string;
 
     /**
-     * The contact's last name.
+     * The new contact's last name.
      */
     @IsNotEmpty()
     @IsString()
     lastname: string;
 
     /**
-     * The contact's address.
-     * Optional
+     * The new contact's address.
+     * Must be the address's id.
      */
     @IsInt()
     @IsOptional()
@@ -38,7 +40,7 @@ export class CreateGroupContact {
 
     /**
      * The contact's phone number.
-     * Optional
+     * This will be validated against the configured country phone numer syntax (default: international).
      */
     @IsOptional()
     @IsPhoneNumber(config.phone_validation_countrycode)
@@ -46,14 +48,13 @@ export class CreateGroupContact {
 
     /**
      * The contact's email address.
-     * Optional
      */
     @IsOptional()
     @IsEmail()
     email?: string;
 
     /**
-     * Get's this participant's address from this.address.
+     * Gets the new contact's address by it's id.
      */
     public async getAddress(): Promise<Address> {
         if (this.address === undefined || this.address === null) {
@@ -69,7 +70,7 @@ export class CreateGroupContact {
     }
 
     /**
-     * Creates a Address object based on this.
+     * Creates a new Address entity from this.
      */
     public async toGroupContact(): Promise<GroupContact> {
         let contact: GroupContact = new GroupContact();

src/models/actions/CreateParticipant.ts

@@ -4,6 +4,9 @@ import { config } from '../../config';
 import { AddressNotFoundError, AddressWrongTypeError } from '../../errors/AddressErrors';
 import { Address } from '../entities/Address';
 
+/**
+ * This classed is used to create a new Participant entity from a json body (post request).
+ */
 export abstract class CreateParticipant {
     /**
      * The new participant's first name.
@@ -14,7 +17,6 @@ export abstract class CreateParticipant {
 
     /**
      * The new participant's middle name.
-     * Optional.
      */
     @IsString()
     @IsOptional()
@@ -29,7 +31,7 @@ export abstract class CreateParticipant {
 
     /**
      * The new participant's phone number.
-     * Optional.
+     * This will be validated against the configured country phone numer syntax (default: international).
      */
     @IsString()
     @IsOptional()
@@ -38,7 +40,6 @@ export abstract class CreateParticipant {
 
     /**
      * The new participant's e-mail address.
-     * Optional.
      */
     @IsString()
     @IsOptional()
@@ -48,14 +49,13 @@ export abstract class CreateParticipant {
     /**
      * The new participant's address.
      * Must be of type number (address id).
-     * Optional.
      */
     @IsInt()
     @IsOptional()
     address?: number;
 
     /**
-     * Get's this participant's address from this.address.
+     * Gets the new participant's address by it's address.
      */
     public async getAddress(): Promise<Address> {
         if (this.address === undefined || this.address === null) {

src/models/actions/CreatePermission.ts

@@ -11,33 +11,33 @@ import { PermissionAction } from '../enums/PermissionAction';
 import { PermissionTarget } from '../enums/PermissionTargets';
 
 /**
- * Defines a track of given length.
-*/
+ * This classed is used to create a new Permission entity from a json body (post request).
+ */
 export class CreatePermission {
 
     /**
-     * The permissions's principal's id.
+     * The new permissions's principal's id.
      */
     @IsInt()
     @IsNotEmpty()
     principal: number;
 
     /**
-     * The permissions's target.
+     * The new permissions's target.
      */
     @IsNotEmpty()
     @IsEnum(PermissionTarget)
     target: PermissionTarget;
 
     /**
-     * The permissions's action.
+     * The new permissions's action.
      */
     @IsNotEmpty()
     @IsEnum(PermissionAction)
     action: PermissionAction;
 
     /**
-     * Converts a Permission object based on this.
+     * Creates a new Permission entity from this.
      */
     public async toPermission(): Promise<Permission> {
         let newPermission: Permission = new Permission();
@@ -49,6 +49,9 @@ export class CreatePermission {
         return newPermission;
     }
 
+    /**
+     * Gets the new permission's principal by it's id.
+     */
     public async getPrincipal(): Promise<Principal> {
         let principal = await getConnectionManager().get().getRepository(Principal).findOne({ id: this.principal })
         if (!principal) { throw new PrincipalNotFoundError(); }

src/models/actions/CreateRunner.ts

@@ -7,6 +7,9 @@ import { Runner } from '../entities/Runner';
 import { RunnerGroup } from '../entities/RunnerGroup';
 import { CreateParticipant } from './CreateParticipant';
 
+/**
+ * This classed is used to create a new Runner entity from a json body (post request).
+ */
 export class CreateRunner extends CreateParticipant {
 
     /**
@@ -16,7 +19,7 @@ export class CreateRunner extends CreateParticipant {
     group: number;
 
     /**
-     * Creates a Runner entity from this.
+     * Creates a new Runner entity from this.
      */
     public async toRunner(): Promise<Runner> {
         let newRunner: Runner = new Runner();
@@ -33,7 +36,7 @@ export class CreateRunner extends CreateParticipant {
     }
 
     /**
-     * Manages all the different ways a group can be provided.
+     * Gets the new runner's group by it's id.
      */
     public async getGroup(): Promise<RunnerGroup> {
         if (this.group === undefined || this.group === null) {

src/models/actions/CreateRunnerGroup.ts

@@ -3,16 +3,19 @@ import { getConnectionManager } from 'typeorm';
 import { GroupContactNotFoundError, GroupContactWrongTypeError } from '../../errors/GroupContactErrors';
 import { GroupContact } from '../entities/GroupContact';
 
+/**
+ * This classed is used to create a new RunnerGroup entity from a json body (post request).
+ */
 export abstract class CreateRunnerGroup {
     /**
-     * The group's name.
+     * The new group's name.
      */
     @IsNotEmpty()
     @IsString()
     name: string;
 
     /**
-     * The group's contact.
+     * The new group's contact.
      * Optional
      */
     @IsInt()
@@ -20,7 +23,7 @@ export abstract class CreateRunnerGroup {
     contact?: number;
 
     /**
-     * Get's this group's contact from this.address.
+     * Gets the new group's contact by it's id.
      */
     public async getContact(): Promise<GroupContact> {
         if (this.contact === undefined || this.contact === null) {

src/models/actions/CreateRunnerOrganisation.ts

@@ -5,18 +5,20 @@ import { Address } from '../entities/Address';
 import { RunnerOrganisation } from '../entities/RunnerOrganisation';
 import { CreateRunnerGroup } from './CreateRunnerGroup';
 
+/**
+ * This classed is used to create a new RunnerOrganisation entity from a json body (post request).
+ */
 export class CreateRunnerOrganisation extends CreateRunnerGroup {
     /**
      * The new organisation's address.
      * Must be of type number (address id).
-     * Optional.
      */
     @IsInt()
     @IsOptional()
     address?: number;
 
     /**
-     * Get's this org's address from this.address.
+     * Gets the org's address by it's id.
      */
     public async getAddress(): Promise<Address> {
         if (this.address === undefined || this.address === null) {
@@ -32,7 +34,7 @@ export class CreateRunnerOrganisation extends CreateRunnerGroup {
     }
 
     /**
-     * Creates a RunnerOrganisation entity from this.
+     * Creates a new RunnerOrganisation entity from this.
      */
     public async toRunnerOrganisation(): Promise<RunnerOrganisation> {
         let newRunnerOrganisation: RunnerOrganisation = new RunnerOrganisation();

src/models/actions/CreateRunnerTeam.ts

@@ -6,15 +6,21 @@ import { RunnerOrganisation } from '../entities/RunnerOrganisation';
 import { RunnerTeam } from '../entities/RunnerTeam';
 import { CreateRunnerGroup } from './CreateRunnerGroup';
 
+/**
+ * This classed is used to create a new RunnerTeam entity from a json body (post request).
+ */
 export class CreateRunnerTeam extends CreateRunnerGroup {
 
     /**
-     * The team's parent group (organisation).
+     * The new team's parent group (organisation).
      */
     @IsInt()
     @IsNotEmpty()
     parentGroup: number;
 
+    /**
+     * Gets the new team's parent org based on it's id.
+     */
     public async getParent(): Promise<RunnerOrganisation> {
         if (this.parentGroup === undefined || this.parentGroup === null) {
             throw new RunnerTeamNeedsParentError();
@@ -29,7 +35,7 @@ export class CreateRunnerTeam extends CreateRunnerGroup {
     }
 
     /**
-     * Creates a RunnerTeam entity from this.
+     * Creates a new RunnerTeam entity from this.
      */
     public async toRunnerTeam(): Promise<RunnerTeam> {
         let newRunnerTeam: RunnerTeam = new RunnerTeam();

src/models/actions/CreateTrack.ts

@@ -1,23 +1,26 @@
 import { IsInt, IsNotEmpty, IsPositive, IsString } from 'class-validator';
 import { Track } from '../entities/Track';
 
+/**
+ * This classed is used to create a new Track entity from a json body (post request).
+ */
 export class CreateTrack {
     /**
-     * The track's name.
+     * The new track's name.
      */
     @IsString()
     @IsNotEmpty()
     name: string;
 
     /**
-     * The track's distance in meters (must be greater than 0).
+     * The new track's distance in meters (must be greater than 0).
      */
     @IsInt()
     @IsPositive()
     distance: number;
 
     /**
-     * Converts a Track object based on this.
+     * Creates a new Track entity from this.
      */
     public toTrack(): Track {
         let newTrack: Track = new Track();

src/models/actions/CreateUser.ts

@@ -8,6 +8,9 @@ import { UserGroupNotFoundError } from '../../errors/UserGroupErrors';
 import { User } from '../entities/User';
 import { UserGroup } from '../entities/UserGroup';
 
+/**
+ * This classed is used to create a new User entity from a json body (post request).
+ */
 export class CreateUser {
     /**
      * The new user's first name.
@@ -17,7 +20,6 @@ export class CreateUser {
 
     /**
      * The new user's middle name.
-     * Optinal.
      */
     @IsString()
     @IsOptional()
@@ -48,7 +50,7 @@ export class CreateUser {
 
     /**
      * The new user's phone number.
-     * Optional
+     * This will be validated against the configured country phone numer syntax (default: international).
      */
     @IsPhoneNumber(config.phone_validation_countrycode)
     @IsOptional()
@@ -64,7 +66,6 @@ export class CreateUser {
     /**
      * The new user's groups' id(s).
      * You can provide either one groupId or an array of groupIDs.
-     * Optional.
      */
     @IsOptional()
     groups?: number[] | number
@@ -72,7 +73,7 @@ export class CreateUser {
     //TODO: ProfilePics
 
     /**
-     * Converts this to a User Entity.
+     * Converts this to a User entity.
      */
     public async toUser(): Promise<User> {
         let newUser: User = new User();

src/models/actions/CreateUserGroup.ts

@@ -1,6 +1,9 @@
 import { IsOptional, IsString } from 'class-validator';
 import { UserGroup } from '../entities/UserGroup';
 
+/**
+ * This classed is used to create a new UserGroup entity from a json body (post request).
+ */
 export class CreateUserGroup {
     /**
      * The new group's name.
@@ -17,7 +20,7 @@ export class CreateUserGroup {
     description?: string;
 
     /**
-     * Converts this to a UserGroup entity.
+     * Creates a new UserGroup entity from this.
      */
     public async toUserGroup(): Promise<UserGroup> {
         let newUserGroup: UserGroup = new UserGroup();