add docstrings

Author: ryanslatten

web-app/admin/src/app/admin/admin-teams/create-team/create-team.component.ts

@@ -4,6 +4,10 @@ import { FormBuilder, FormGroup, Validators } from '@angular/forms';
 import { TeamsService } from '../teams-service';
 import { Team } from '../team';
 
+/**
+ * Dialog component for creating new teams.
+ * Provides a form interface with validation for team name (required) and description (optional).
+ */
 @Component({
     selector: 'mage-admin-team-create',
     templateUrl: './create-team.component.html',
@@ -25,6 +29,10 @@ export class CreateTeamDialogComponent {
         });
     }
 
+    /**
+     * Handles form submission for creating a new team.
+     * Validates the form, creates the team via the teams service, and closes the dialog on success.
+     */
     save(): void {
         if (this.teamForm.invalid) {
             this.errorMessage = 'Please fill in all required fields.';
@@ -43,6 +51,9 @@ export class CreateTeamDialogComponent {
         });
     }
 
+    /**
+     * Closes the dialog without saving any data or making any changes.
+     */
     cancel(): void {
         this.dialogRef.close();
     }

web-app/admin/src/app/admin/admin-teams/dashboard/team-dashboard.component.ts

@@ -8,6 +8,10 @@ import { TeamsService } from '../teams-service';
 import { CreateTeamDialogComponent } from '../create-team/create-team.component';
 import { CardActionButton } from '../../../core/card-navbar/card-navbar.component';
 
+/**
+ * Team dashboard component that displays a paginated list of teams with search functionality.
+ * Provides capabilities to view, search, and create new teams through a data table interface.
+ */
 @Component({
   selector: 'mage-admin-teams',
   templateUrl: './team-dashboard.component.html',
@@ -33,15 +37,24 @@ export class TeamDashboardComponent implements OnInit, OnDestroy {
     private teamService: TeamsService
   ) { }
 
+  /**
+   * Fetches the initial set of teams when the component loads
+   */
   ngOnInit(): void {
     this.fetchTeams();
   }
 
+  /**
+   * Component destruction lifecycle hook
+   */
   ngOnDestroy(): void {
     this.destroy$.next();
     this.destroy$.complete();
   }
 
+  /**
+   * Fetches teams from the service based on current search term and pagination settings
+   */
   fetchTeams(): void {
     this.teamService.getTeams({
       term: this.teamSearch,
@@ -58,24 +71,41 @@ export class TeamDashboardComponent implements OnInit, OnDestroy {
     });
   }
 
+  /**
+   * Handles pagination change events from the Material paginator
+   * 
+   * @param event - The page event containing new page size and index
+   */
   onPageChange(event: PageEvent): void {
     this.pageSize = event.pageSize;
     this.pageIndex = event.pageIndex;
     this.fetchTeams();
   }
 
+  /**
+   * Resets pagination to the first page and refetches teams with the new search term
+   * 
+   * @param term - The new search term entered by the user
+   */
   onSearchTermChanged(term: string): void {
     this.teamSearch = term;
     this.pageIndex = 0; // Reset to first page when searching
     this.fetchTeams();
   }
 
+  /**
+   * Resets the search term, pagination to the first page, and refetches all teams
+   */
   onSearchCleared(): void {
     this.teamSearch = '';
     this.pageIndex = 0;
     this.fetchTeams();
   }
 
+  /**
+   * Opens the create team dialog and handles the result.
+   * If a new team is created, refetches the teams list to include the new team.
+   */
   newTeam(): void {
     const dialogRef = this.modal.open(CreateTeamDialogComponent, {
       width: '50rem',
@@ -90,6 +120,11 @@ export class TeamDashboardComponent implements OnInit, OnDestroy {
     });
   }
 
+  /**
+   * Navigates to the detailed view of a specific team
+   * 
+   * @param team - The team to navigate to
+   */
   gotoTeam(team: Team): void {
     // TODO: convert to this to using a router once upgrade is complete
     const baseUrl = window.location.href.split('#')[0];

web-app/admin/src/app/core/card-navbar/card-navbar.component.html

@@ -7,7 +7,8 @@ <h3 class="navbar-brand">{{ title }}</h3>
         <div class="navbar-form navbar-left search-container" *ngIf="isSearchable">
             <input type="text" class="form-control search-input" [placeholder]="searchPlaceholder"
                 [(ngModel)]="searchTerm" (ngModelChange)="onSearchChange($event)">
-            <button type="button" class="btn clear-search-btn" (click)="clearSearch()">
+            <button type="button" class="btn clear-search-btn" (click)="clearSearch()"
+                *ngIf="searchTerm && searchTerm.trim()">
                 <i class="fa fa-times"></i>
             </button>
         </div>

web-app/admin/src/app/core/card-navbar/card-navbar.component.ts

@@ -9,6 +9,11 @@ export interface CardActionButton {
   action: () => void;
 }
 
+/**
+ * A reusable card navbar component that provides a title, optional search functionality,
+ * and configurable action buttons. The component handles search debouncing and emits
+ * events for search term changes and search clearing.
+ */
 @Component({
   selector: 'mage-card-navbar',
   templateUrl: './card-navbar.component.html',
@@ -31,6 +36,9 @@ export class CardNavbarComponent implements OnInit, OnDestroy {
 
   constructor() { }
 
+  /**
+   * Sets up the search subject with debouncing and change detection.
+   */
   ngOnInit(): void {
     this.searchSubject$.pipe(
       debounceTime(this.debounceTime),
@@ -41,23 +49,39 @@ export class CardNavbarComponent implements OnInit, OnDestroy {
     });
   }
 
+  /**
+   * Component destruction lifecycle hook
+   */
   ngOnDestroy(): void {
     this.destroy$.next();
     this.destroy$.complete();
   }
 
+  /**
+   * Clears the search input and emits the searchCleared event
+   */
   clearSearch(): void {
     this.searchTerm = '';
     this.searchSubject$.next('');
     this.searchCleared.emit();
   }
 
+  /**
+   * Handles action button click events
+   * 
+   * @param button - The action button that was clicked
+   */
   onActionButtonClick(button: CardActionButton): void {
     if (button.action) {
       button.action();
     }
   }
 
+  /**
+   * Handles search input changes
+   * 
+   * @param term - The new search term entered by the user
+   */
   onSearchChange(term: string): void {
     this.searchTerm = term;
     this.searchSubject$.next(term);