Angular Doc

Important Notice

While using ChatGPT, don't copy-paste exact content. Read carefully and make necessary changes.

1. Introduction

This document outlines the coding standards and best practices for developing Angular applications within SIONIQ. It covers aspects such as component architecture, services, performance, testing, and styling. Following these standards ensures consistency, maintainability, and high-quality code.

2. Angular Documentation Standards

In Angular, it is essential to properly document models and interfaces to enhance code readability, maintainability, and team collaboration. Use JSDoc comments to document the purpose and usage of each property in the model. Below are the standards and examples of how to document an interface.

2.1 Model Interface Documentation
Without JSDoc Comments

In this section, we provide an example of how the interface looks without JSDoc comments. 


export interface AddCategoryRequest 
{
    name: string;
    urlHandle: string;
}
Use ChatGpt

Copy paste the row code in the ChatGpt and type "Inclulde JSDoc Comments in the code".

With JSDoc Comments

Below is an example of the same interface but with JSDoc comments added to document the purpose of each property. 


/**
 * Interface representing a request to add a new category.
 * @interface
 */
export interface AddCategoryRequest {
    /**
     * The name of the category.
     * This field holds the name of the category being added.
     * @type {string}
     */
    name: string;

    /**
     * A unique URL handle for the category, used for routing and SEO purposes.
     * This is a URL-safe string that represents the category for routing and SEO optimization.
     * @type {string}
     */
    urlHandle: string;
}
2.2 Component Documentation
Without JSDoc Comments

In this section, we provide an example of how the interface looks without JSDoc comments. 


 import { Component, OnDestroy } from '@angular/core';
 import { AddCategoryRequest } from '../models/add-category-request.model';
 import { CategoryService } from '../services/category.service';
 import { Subscription } from 'rxjs';
 import { Router } from '@angular/router';
 
 
 @Component({
 selector: 'app-add-category',
 templateUrl: './add-category.component.html',
 styleUrls: ['./add-category.component.css']
 })
 export class AddCategoryComponent implements OnDestroy {
 
 
 model: AddCategoryRequest;
 
 
 private addCategorySubscription?: Subscription;
 
 
 constructor(private categoryService: CategoryService, private router: Router) {
 this.model = {
 name: '',
 urlHandle: ''
 };
 }
 
 
 onFormSubmit() {
 this.addCategorySubscription = this.categoryService.addCategory(this.model)
 .subscribe({
 next: (response) => {
 this.router.navigateByUrl('/admin/categories');
 }
 });
 }
 
 
 ngOnDestroy(): void {
 this.addCategorySubscription?.unsubscribe();
 }
 }
Use ChatGpt

Copy paste the row code in the ChatGpt and type "Inclulde JSDoc Comments in the code".

With JSDoc Comments

Below is an example of the same interface but with JSDoc comments added to document the purpose of each property. 


import { Component, OnDestroy } from '@angular/core';
import { AddCategoryRequest } from '../models/add-category-request.model';
import { CategoryService } from '../services/category.service';
import { Subscription } from 'rxjs';
import { Router } from '@angular/router';

/**
* Component for adding a new category.
*
* This component handles the submission of a category form and
* communicates with the category service to add a new category.
*/
@Component({
selector: 'app-add-category',
templateUrl: './add-category.component.html',
styleUrls: ['./add-category.component.css']
})
export class AddCategoryComponent implements OnDestroy {

/**
* The model representing the category to be added.
* @type {AddCategoryRequest}
*/
model: AddCategoryRequest;

/**
* Subscription for the addCategory observable.
* @type {Subscription | undefined}
*/
private addCategorySubscription?: Subscription;

/**
* Creates an instance of AddCategoryComponent.
* @param {CategoryService} categoryService - The service for managing categories.
* @param {Router} router - The router for navigation.
*/
constructor(private categoryService: CategoryService, private router: Router) {
this.model = {
name: '',
urlHandle: ''
};
}

/**
* Handles the form submission for adding a category.
* This method subscribes to the addCategory service and navigates to the
* categories page upon a successful response.
*
* @returns {void}
*
* @example
* // Triggered when the form is submitted
* onFormSubmit();
*/
onFormSubmit() {
this.addCategorySubscription = this.categoryService.addCategory(this.model)
.subscribe({
next: (response) => {
this.router.navigateByUrl('/admin/categories');
}
});
}

/**
* Cleans up subscriptions when the component is destroyed.
*
* @returns {void}
*/
ngOnDestroy(): void {
this.addCategorySubscription?.unsubscribe();
}
}
2.3 Service Documentation
Without JSDoc Comments

In this section, we provide an example of how the interface looks without JSDoc comments. 


import { Injectable } from '@angular/core';
import { AddCategoryRequest } from '../models/add-category-request.model';
import { Observable } from 'rxjs';
import { HttpClient } from '@angular/common/http';
import { Category } from '../models/category.model';
import { environment } from '../../../../environments/environment';
import { UpdateCategoryRequest } from '../models/update-category-request.model';


@Injectable({
  providedIn: 'root'
})
export class CategoryService {

  constructor(private http: HttpClient) { }


  addCategory(model: AddCategoryRequest): Observable {
    return this.http.post(`${environment.apiBaseUrl}/api/categories`, model);
  }


  getAllCategories(): Observable {
    return this.http.get(`${environment.apiBaseUrl}/api/categories`);
  }


  getCategoryById(id: string): Observable {
    return this.http.get(`${environment.apiBaseUrl}/api/categories/${id}`);
  }


  updateCategory(id: string, updateCategoryRequest: UpdateCategoryRequest): Observable {
    return this.http.put(`${environment.apiBaseUrl}/api/categories/${id}`, updateCategoryRequest);
  }


  deleteCategory(id: string): Observable {
    return this.http.delete(`${environment.apiBaseUrl}/api/categories/${id}`);
  }

}
Use ChatGpt

Copy paste the row code in the ChatGpt and type "Inclulde JSDoc Comments in the code".

With JSDoc Comments

Below is an example of the same interface but with JSDoc comments added to document the purpose of each property. 


import { Component, OnDestroy } from '@angular/core';
import { AddCategoryRequest } from '../models/add-category-request.model';
import { CategoryService } from '../services/category.service';
import { Subscription } from 'rxjs';
import { Router } from '@angular/router';

/**
* Component for adding a new category.
*
* This component handles the submission of a category form and
* communicates with the category service to add a new category.
*/
@Component({
selector: 'app-add-category',
templateUrl: './add-category.component.html',
styleUrls: ['./add-category.component.css']
})
export class AddCategoryComponent implements OnDestroy {

/**
* The model representing the category to be added.
* @type {AddCategoryRequest}
*/
model: AddCategoryRequest;

/**
* Subscription for the addCategory observable.
* @type {Subscription | undefined}
*/
private addCategorySubscription?: Subscription;

/**
* Creates an instance of AddCategoryComponent.
* @param {CategoryService} categoryService - The service for managing categories.
* @param {Router} router - The router for navigation.
*/
constructor(private categoryService: CategoryService, private router: Router) {
this.model = {
name: '',
urlHandle: ''
};
}

/**
* Handles the form submission for adding a category.
* This method subscribes to the addCategory service and navigates to the
* categories page upon a successful response.
*
* @returns {void}
*
* @example
* // Triggered when the form is submitted
* onFormSubmit();
*/
onFormSubmit() {
this.addCategorySubscription = this.categoryService.addCategory(this.model)
.subscribe({
next: (response) => {
this.router.navigateByUrl('/admin/categories');
}
});
}

/**
* Cleans up subscriptions when the component is destroyed.
*
* @returns {void}
*/
ngOnDestroy(): void {
this.addCategorySubscription?.unsubscribe();
}
}
2.4 Guidelines for JSDoc Comments in Models