jsdoc: Add class comments to main rendering classes

Author: claremacrae

src/Obsidian/InlineRenderer.ts

@@ -8,6 +8,20 @@ import { Task } from '../Task/Task';
 import { TaskLineRenderer } from '../Renderer/TaskLineRenderer';
 import { TaskLocation } from '../Task/TaskLocation';
 
+/**
+ * An inline renderer for processing and rendering tasks in the Reading View of an Obsidian file.
+ *
+ * This class processes task lists using the same pipeline as the {@link QueryRenderer} while modifying specific components
+ * like removing the global filter and handling task formatting.
+ *
+ * Bug reports associated with this code: (label:"display: reading mode")
+ * https://github.com/obsidian-tasks-group/obsidian-tasks/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22display%3A%20reading%20mode%22%20label%3A%22type%3A%20bug%22
+ *
+ * And probably also: (label:"scope: rendering of tasks")
+ * https://github.com/obsidian-tasks-group/obsidian-tasks/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22type%3A%20bug%22%20label%3A%22scope%3A%20rendering%20of%20tasks%22
+ *
+ * See also {@link LivePreviewExtension} which handles Markdown task lines in Obsidian's Live Preview mode.
+ */
 export class InlineRenderer {
     constructor({ plugin }: { plugin: Plugin }) {
         plugin.registerMarkdownPostProcessor(this._markdownPostProcessor.bind(this));

src/Obsidian/LivePreviewExtension.ts

@@ -10,6 +10,17 @@ export const newLivePreviewExtension = () => {
     return ViewPlugin.fromClass(LivePreviewExtension);
 };
 
+/**
+ * Integrate custom handling of checkbox clicks in the Obsidian editor's Live Preview mode.
+ *
+ * This class is primarily designed for checkbox-driven task management in the Obsidian plugin, overriding the default handling behavior.
+ * It listens for click events, detects checkbox interactions, and updates the document state accordingly.
+ *
+ * Bug reports associated with this code: (label:"display: live preview")
+ * https://github.com/obsidian-tasks-group/obsidian-tasks/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22display%3A%20live%20preview%22%20label%3A%22type%3A%20bug%22
+ *
+ * See also {@link InlineRenderer} which handles Markdown task lines in Obsidian's Reading mode.
+ */
 class LivePreviewExtension implements PluginValue {
     private readonly view: EditorView;
 

src/Renderer/QueryRenderer.ts

@@ -21,6 +21,13 @@ import type { Task } from '../Task/Task';
 import { type BacklinksEventHandler, type EditButtonClickHandler, QueryResultsRenderer } from './QueryResultsRenderer';
 import { createAndAppendElement } from './TaskLineRenderer';
 
+/**
+ * `QueryRenderer` is responsible for rendering queries in Markdown code blocks
+ * annotated with the 'tasks' processor.
+ *
+ * It manages the initialization of query rendering related tasks, processing metadata,
+ * and adding rendered content to the DOM.
+ */
 export class QueryRenderer {
     private readonly app: App;
     private readonly plugin: TasksPlugin;
@@ -64,6 +71,15 @@ export class QueryRenderer {
     }
 }
 
+/**
+ * A class that extends {@link MarkdownRenderChild} to render query results dynamically in Obsidian.
+ *
+ * This class listens to various Obsidian events such as metadata updates, cache changes, and
+ * file renames, and re-renders query results when relevant data changes. It supports dynamic
+ * updates, including reloading query results at midnight to ensure accurate relative date queries.
+ *
+ * The generation of HTML to render task lines is done by {@link QueryResultsRenderer}.
+ */
 class QueryRenderChild extends MarkdownRenderChild {
     private readonly app: App;
     private readonly plugin: TasksPlugin;

src/Renderer/QueryResultsRenderer.ts

@@ -21,6 +21,13 @@ import { TaskLineRenderer, type TextRenderer, createAndAppendElement } from './T
 export type BacklinksEventHandler = (ev: MouseEvent, task: Task) => Promise<void>;
 export type EditButtonClickHandler = (event: MouseEvent, task: Task, allTasks: Task[]) => void;
 
+/**
+ * Represent the parameters required for rendering a query with {@link QueryResultsRenderer}.
+ *
+ * This interface contains all the necessary properties and handlers to manage
+ * and display query results such as tasks, markdown files, and certain event handlers
+ * for user interactions, like handling backlinks and editing tasks.
+ */
 export interface QueryRendererParameters {
     allTasks: Task[];
     allMarkdownFiles: TFile[];
@@ -29,6 +36,12 @@ export interface QueryRendererParameters {
     editTaskPencilClickHandler: EditButtonClickHandler;
 }
 
+/**
+ * The `QueryResultsRenderer` class is responsible for rendering the results
+ * of a query applied to a set of tasks.
+ *
+ * It handles the construction of task groupings and the application of visual styles.
+ */
 export class QueryResultsRenderer {
     /**
      * The complete text in the instruction block, such as:

src/Renderer/TaskFieldRenderer.ts

@@ -4,6 +4,14 @@ import type { TaskLayoutComponent } from '../Layout/TaskLayoutOptions';
 import { PriorityTools } from '../lib/PriorityTools';
 import type { Task } from '../Task/Task';
 
+/**
+ * A renderer for individual {@link Task} fields in an HTML context.
+ *
+ * This class provides methods to add data attributes and CSS class names to
+ * HTML elements based on specific task-related components.
+ *
+ * See also {@link TaskLineRenderer} which renders all the fields in a task.
+ */
 export class TaskFieldRenderer {
     private readonly data = taskFieldHTMLData;
 

src/Renderer/TaskLineRenderer.ts

@@ -53,6 +53,15 @@ export function createAndAppendElement<K extends keyof HTMLElementTagNameMap>(
     return el;
 }
 
+/**
+ * `TaskLineRenderer` is responsible for rendering task details as HTML list items with
+ * various customization options.
+ *
+ * It integrates with Obsidian's rendering system and includes functionalities such as priority,
+ * due dates, and user interactions.
+ *
+ * Individual fields in {@link Task} are rendered by {@link TaskFieldRenderer}.
+ */
 export class TaskLineRenderer {
     private readonly textRenderer: TextRenderer;
     private readonly obsidianComponent: Component | null;