[DURACOM-508] add inline documentation

Author: FrancescoMolinaro

src/app/core/data/paginated-list.model.ts

@@ -103,8 +103,6 @@ export class PaginatedList<T> extends CacheableObject {
     prev?: HALLink;
     next?: HALLink;
     last?: HALLink;
-    missing?: HALLink;
-    more?: HALLink;
   };
 
   get elementsPerPage(): number {

src/app/core/data/section-data.service.ts

@@ -47,7 +47,8 @@ export class SectionDataService extends IdentifiableDataService<Section> {
   }
 
   /**
-   * Find all the configured sections.
+   * Finds all sections configured to be visible in the top navigation bar.
+   * Uses the 'visibleTopBarSections' search endpoint on the backend.
    */
   findVisibleSections(): Observable<RemoteData<PaginatedList<Section>>> {
     return this.searchData.searchBy('visibleTopBarSections');

src/app/core/layout/models/section.model.ts

@@ -46,59 +46,110 @@ export class Section extends CacheableObject {
 
 }
 
+/**
+ * Base interface for all section component configurations returned by the REST API.
+ */
 export interface SectionComponent {
+  /** The type discriminator identifying which component to render. */
   componentType: string;
+  /** CSS classes applied to the section container (e.g., Bootstrap grid classes). */
   style: string;
 }
 
+/**
+ * Configuration for a browse section that displays links to browse indices.
+ */
 export interface BrowseSection extends SectionComponent {
+  /** List of browse index names to render as navigation links. */
   browseNames: string[];
   componentType: 'browse';
 }
 
+/**
+ * Configuration for a top section that displays the most recent/popular items
+ * from a discovery configuration.
+ */
 export interface TopSection extends SectionComponent {
+  /** Name of the discovery configuration to query. */
   discoveryConfigurationName: string;
+  /** Metadata field to sort results by. */
   sortField: string;
+  /** Sort direction ('ASC' or 'DESC'). */
   order: string;
+  /** i18n key for the section title. */
   titleKey: string;
   componentType: 'top';
+  /** Maximum number of items to display. */
   numberOfItems: number;
+  /** Whether to show item thumbnails. */
   showThumbnails: boolean;
+  /** Template type to use for rendering the items. */
   template: TopSectionTemplateType;
 }
 
+/**
+ * Configuration for an advanced search section with multiple query statements and filter fields.
+ */
 export interface SearchSection extends SectionComponent {
+  /** Name of the discovery configuration providing available filters. */
   discoveryConfigurationName: string;
   componentType: 'search';
+  /** Type of search interface to render. */
   searchType: string;
+  /** Number of query statement rows to display initially. */
   initialStatements: number;
+  /** Whether to display the section title. */
   displayTitle: boolean;
 }
 
+/**
+ * Configuration for a section displaying search facets from a discovery configuration.
+ */
 export interface FacetSection extends SectionComponent {
+  /** Name of the discovery configuration to fetch facet values from. */
   discoveryConfigurationName: string;
   componentType: 'facet';
+  /** Number of facet boxes to display per row in the grid. */
   facetsPerRow: number;
 }
 
+/**
+ * Configuration for a text content section that renders static or metadata-based content.
+ */
 export interface TextRowSection extends SectionComponent {
+  /** The content string (can be a metadata key or raw content depending on contentType). */
   content: string;
+  /** The type of content: e.g., 'text-metadata' for metadata lookups or 'text-raw' for static content. */
   contentType: string;
   componentType: 'text-row';
 }
 
+/**
+ * Configuration for a table-like section showing top items with multiple metadata columns.
+ */
 export interface MultiColumnTopSection extends SectionComponent {
+  /** Name of the discovery configuration to query. */
   discoveryConfigurationName: string;
+  /** Metadata field to sort results by. */
   sortField: string;
+  /** Sort direction ('ASC' or 'DESC'). */
   order: string;
+  /** i18n key for the section title. */
   titleKey: string;
+  /** List of column definitions specifying which metadata fields to display. */
   columnList: TopSectionColumn[];
   componentType: 'multi-column-top';
 }
 
+/**
+ * Column configuration for {@link MultiColumnTopSection} defining which metadata to display.
+ */
 export interface TopSectionColumn {
+  /** CSS classes for column width styling. */
   style: string;
+  /** Metadata field to extract the column value from. */
   metadataField: string;
+  /** i18n key for the column header. */
   titleKey: string;
 }
 

src/app/explore-page/explore-i18n-breadcrumb.resolver.ts

@@ -12,8 +12,9 @@ import { hasNoValue } from '../utils/empty.util';
 
 
 /**
- * This class resolves a BreadcrumbConfig object with an i18n key string for a route
- * It adds the metadata field of the current explore page
+ * Resolves a BreadcrumbConfig object with an i18n key string for an explore route.
+ * Extends the base breadcrumb key with the explore page's ID route parameter
+ * (e.g., 'explore' becomes 'explore.publications') to provide page-specific breadcrumb labels.
  */
 export const exploreI18nBreadcrumbResolver: ResolveFn<BreadcrumbConfig<string>> = (
   route: ActivatedRouteSnapshot,

src/app/explore-page/explore-page.component.ts

@@ -24,7 +24,11 @@ import { ThemedTextSectionComponent } from '../shared/explore/section-component/
 import { ThemedTopSectionComponent } from '../shared/explore/section-component/top-section/themed-top-section.component';
 
 /**
- * Component representing the explore section.
+ * Main container component for dynamic explore pages.
+ *
+ * Fetches section configuration from the backend based on the current route parameter
+ * and renders the configured sections as a responsive grid of section components.
+ * Supported section types include: top, browse, search, facet, text-row, and counters.
  */
 @Component({
   selector: 'ds-explore',
@@ -43,13 +47,14 @@ import { ThemedTopSectionComponent } from '../shared/explore/section-component/t
 export class ExplorePageComponent implements OnInit {
 
   /**
-     * The id of the current section.
-     */
+   * Identifier for the current explore section, derived from the ':id' route parameter.
+   */
   sectionId: string;
 
   /**
-     * Resolved section components splitted in rows.
-     */
+   * Observable emitting a 2D array of section components organized in rows for grid layout.
+   * Each inner array represents a row of components to be rendered side-by-side.
+   */
   sectionComponentRows: Observable<SectionComponent[][]>;
 
   constructor(
@@ -61,10 +66,11 @@ export class ExplorePageComponent implements OnInit {
   }
 
   /**
-     * Setup the section components of the explore page based on the section id.
-     *
-     * @param params the route params
-     */
+   * Fetches the section configuration from the backend and resolves
+   * the section's component rows into the {@link sectionComponentRows} observable.
+   *
+   * @param params the route params containing the explore section 'id'
+   */
   setupSectionComponents( params: Params ) {
     this.sectionId = params.id;
     this.sectionComponentRows = this.sectionDataService.findById(params.id ).pipe(
@@ -74,8 +80,11 @@ export class ExplorePageComponent implements OnInit {
   }
 
   /**
-   * Check if style contains 'col' or 'col-x'
-   * @param style the style of the cell (a list of classes separated by space)
+   * Checks if a style string already contains a Bootstrap column class (e.g. 'col' or 'col-*').
+   * Used to determine whether a default column class should be applied to a grid cell.
+   *
+   * @param style the style of the cell (a space-separated list of CSS classes)
+   * @returns true if the style contains a Bootstrap column class
    */
   hasColClass(style) {
     return style?.split(' ').filter((c) => (c === 'col' || c.startsWith('col-'))).length > 0;

src/app/explore-page/explore-routes.ts

@@ -1,3 +1,8 @@
+/**
+ * Route definitions for the explore module.
+ * Maps ':id' paths to the {@link ExplorePageComponent}, resolving breadcrumbs
+ * via {@link exploreI18nBreadcrumbResolver} and guarding access with the end-user agreement.
+ */
 import { Route } from '@angular/router';
 
 import { endUserAgreementCurrentUserGuard } from '../core/end-user-agreement/end-user-agreement-current-user.guard';

src/app/home-page/home-page.component.ts

@@ -62,6 +62,14 @@ import { ThemedHomeNewsComponent } from './home-news/themed-home-news.component'
 import { RecentItemListComponent } from './recent-item-list/recent-item-list.component';
 import { ThemedTopLevelCommunityListComponent } from './top-level-community-list/themed-top-level-community-list.component';
 
+/**
+ * The home page component.
+ *
+ * Supports both a static layout and a dynamic layout driven by section configurations
+ * fetched from the REST API. When dynamic layout is enabled (via `enableDynamicLayout` config),
+ * it renders section components similar to the explore page (top, browse, search, facet, text-row, counters).
+ * Also handles COAR Notify inbox link headers and site metadata rendering.
+ */
 @Component({
   selector: 'ds-base-home-page',
   styleUrls: ['./home-page.component.scss'],
@@ -92,16 +100,23 @@ export class HomePageComponent implements OnInit, OnDestroy {
   recentSubmissionspageSize: number;
   showDiscoverFilters: boolean;
   homeHeaderMetadataValue$: Observable<string>;
+
+  /** Whether the dynamic section-based home page layout is enabled via app config. */
   isDynamicHomePageEnabled: boolean;
+
+  /** The section identifier used when fetching the home page layout ('site'). */
   sectionId = 'site';
 
   /**
-   * Two-dimensional array (rows and columns) of section components
+   * Observable emitting a 2D array (rows × columns) of section components
+   * to render when dynamic home page layout is enabled.
    */
   sectionComponents: Observable<SectionComponent[][]>;
 
+  /** Whether the site has a home header metadata value in the current language. */
   hasHomeHeaderMetadata: boolean;
 
+  /** Default text-row section configuration for the home header CMS metadata. */
   homeHeaderSection: TextRowSection = {
     content: 'cris.cms.home-header',
     contentType: 'text-metadata',
@@ -173,6 +188,13 @@ export class HomePageComponent implements OnInit, OnDestroy {
     );
   }
 
+  /**
+   * Returns Bootstrap column classes for a section component.
+   * If the section's style already contains a 'col' class, uses it as-is;
+   * otherwise defaults to 'col-12' prepended to any existing style.
+   *
+   * @param sectionComponent the section component to compute classes for
+   */
   componentClass(sectionComponent: SectionComponent) {
     const defaultCol = 'col-12';
     return (isNotEmpty(sectionComponent.style) && sectionComponent.style.includes('col')) ?

src/app/shared/browse-most-elements/abstract-browse-elements.component.ts

@@ -34,6 +34,12 @@ import {
 import { CollectionElementLinkType } from '../object-collection/collection-element-link.type';
 
 
+/**
+ * Abstract base class for browse elements components.
+ *
+ * Handles searching via the {@link SearchManager} and rendering paginated search results.
+ * Subclasses must specify whether to follow thumbnail links by setting {@link followThumbnailLink}.
+ */
 @Component({
   template: '',
 })
@@ -77,10 +83,13 @@ export abstract class AbstractBrowseElementsComponent implements OnInit, OnChang
 
   public collectionElementLinkTypeEnum = CollectionElementLinkType;
 
+  /** BehaviorSubject emitting the current search options, triggers re-search on change. */
   paginatedSearchOptions$: BehaviorSubject<PaginatedSearchOptions>;
 
+  /** Observable of the raw paginated search results from the SearchManager. */
   searchResults$: Observable<RemoteData<PaginatedList<SearchResult<DSpaceObject>>>>;
 
+  /** Observable emitting the flat array of DSpaceObjects extracted from search results. */
   searchResultArray$: Observable<DSpaceObject[]>;
 
   ngOnChanges() {
@@ -116,6 +125,11 @@ export abstract class AbstractBrowseElementsComponent implements OnInit, OnChang
     );
   }
 
+  /**
+   * Returns the route path for an item's detail page.
+   *
+   * @param item the DSpaceObject (item) to generate a route for
+   */
   getItemPageRoute(item: DSpaceObject | Item) {
     return getItemPageRoute(item as Item);
   }

src/app/shared/browse-most-elements/browse-most-elements.component.ts

@@ -18,6 +18,11 @@ import {
 import { Context } from '../../core/shared/context.model';
 import { ThemedDefaultBrowseElementsComponent } from './default-browse-elements/themed-default-browse-elements.component';
 
+/**
+ * Container component that delegates rendering of browse elements to the appropriate
+ * template component based on the {@link TopSection} configuration.
+ * Currently supports the default template via {@link DefaultBrowseElementsComponent}.
+ */
 @Component({
   selector: 'ds-base-browse-most-elements',
   styleUrls: ['./browse-most-elements.component.scss'],
@@ -66,8 +71,10 @@ export class BrowseMostElementsComponent implements OnInit, OnChanges {
    */
   @Input() topSection: TopSection;
 
+  /** BehaviorSubject re-emitting paginatedSearchOptions to trigger child component updates. */
   paginatedSearchOptions$ = new BehaviorSubject<PaginatedSearchOptions>(null);
 
+  /** The resolved template type determining which child component renders the results. */
   sectionTemplateType: TopSectionTemplateType;
 
   ngOnInit(): void {

src/app/shared/browse-most-elements/default-browse-elements/default-browse-elements.component.ts

@@ -10,6 +10,11 @@ import { ThemedLoadingComponent } from '../../loading/themed-loading.component';
 import { ListableObjectComponentLoaderComponent } from '../../object-collection/shared/listable-object/listable-object-component-loader.component';
 import { AbstractBrowseElementsComponent } from '../abstract-browse-elements.component';
 
+/**
+ * Default template implementation for browsing top elements.
+ * Extends {@link AbstractBrowseElementsComponent} using the standard DSpace
+ * listable object rendering with optional thumbnail support.
+ */
 @Component({
   selector: 'ds-base-default-browse-elements',
   templateUrl: './default-browse-elements.component.html',