chore: Add comments to find locations for common edits (#2437)

* comment: Add NEW_TASK_FIELD_EDIT_REQUIRED to indicate required edits

Some locations are optional, depending on context.

* docs: Add NEW_TASK_FIELD_EDIT_REQUIRED to indicate required edits

Some locations are optional, depending on context.

* comment: Use NEW_QUERY_INSTRUCTION_EDIT_REQUIRED for query edits

* docs: Use NEW_QUERY_INSTRUCTION_EDIT_REQUIRED for query edits

* contrib: Record search-strings for adding fields & query instructions

contributing/Code/How do I add a new field to the Task class.md

@@ -4,6 +4,9 @@
 
 The many steps below can be split over several PRs, to make work - and code review - manageable.
 
+> [!Tip]
+> Search for `NEW_TASK_FIELD_EDIT_REQUIRED` through the code to find locations that are likely to need edits.
+
 ## Releasing a partial implementation
 
 For example, It's fine to have a first release of a feature without `sort by` and `group by`. In this case, add a feature request issue for the missing capabilities, and note in the documentation, for example:

contributing/Code/How do I add a new task filter.md

@@ -2,6 +2,9 @@
 
 All the following steps would be done in the same branch, for inclusion in the same pull request.
 
+> [!Tip]
+> Search for `NEW_QUERY_INSTRUCTION_EDIT_REQUIRED` through the code to find locations that are likely to need edits.
+
 ## Update src/
 
 - Implement the search filter:

docs/Advanced/Styling.md

@@ -33,6 +33,8 @@ The following description relates to a restructuring of the rendered tasks that
 
 The Tasks plugin renders a task in the following structure (this refers to query results, but the Reading View is the same except the top-most containers):
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 ```markdown
 - Obsidian code block (div class="block-language-tasks")
   - Results list (ul class="plugin-tasks-query-result") OR Reading View list (ul class="contains-task-list")
@@ -69,6 +71,8 @@ Data attributes were introduced in Tasks 3.0.0.
 Each rendered task component (description, priority, recurrence rule etc) includes a **generic class** that denotes this type of component.
 The generic classes are:
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 - `task-description`
 - `task-priority`
 - `task-due`
@@ -83,6 +87,7 @@ In addition to the generic classes, there are [**data attributes**](https://deve
 A **priority data attributes** named `data-task-priority` represents the specific priority of a class. It can be `highest`, `high`, `medium`, `low`, `lowest` or `normal`.
 The `normal` value is special: it is added as a default to a task's upper `task-list-item` even if there is no priority field set for that task.
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
 A **date attribute** represents a due, created, start, scheduled or done date in a format relative to the current date.
 The date attributes are `data-task-due`, `data-task-created`, `data-task-start`, `data-task-scheduled` and `data-task-done` and are populated with a relative expression that denotes the number of days this field represents compared to today:
 

docs/Getting Started/Dates.md

@@ -20,6 +20,8 @@ You can find out more in [[Create or edit Task|‘Create or edit Task’ Modal]]
 > [!info]
 > If you prefer to type, it is now very easy to add emojis and other information for you tasks using [[Auto-Suggest|Intelligent Auto-Suggest]].
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 ---
 
 ### Due date

docs/How To/Find tasks with invalid data.md

@@ -28,6 +28,8 @@ Tasks sees as an un-dated task with the text description:
 
 The following tasks block lists any tasks that have emoji in the description, which usually means data that has not been interpreted by Tasks. This is typically because there is some text other than emoji signifiers and tags at the end of the line.
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 ````text
 ```tasks
 # These description instructions need to be all on one line:
@@ -56,6 +58,8 @@ This task has an illegal due date:
 
 The following tasks block lists any tasks with invalid dates, meaning data that has potentially not been interpreted by Tasks.
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED if the new query is for a new date field -->
+
 ````text
 ```tasks
 (done date is invalid) OR (due date is invalid) OR (scheduled date is invalid) OR (start date is invalid)

docs/Queries/Filters.md

@@ -6,6 +6,8 @@ publish: true
 
 <span class="related-pages">#feature/filters</span>
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED -->
+
 ## Contents
 
 This page is long. Here are some links to the main sections:

docs/Queries/Grouping.md

@@ -6,6 +6,8 @@ publish: true
 
 <span class="related-pages">#feature/grouping</span>
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED -->
+
 ## Contents
 
 This page is long. Here are some links to the main sections:

docs/Queries/Layout.md

@@ -11,6 +11,8 @@ together with the name of the element.
 
 The following elements exist:
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED -->
+
 - `edit button`
 - `backlink`
 - `urgency`

docs/Queries/Sorting.md

@@ -4,6 +4,8 @@ publish: true
 
 # Sorting
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED -->
+
 ## Contents
 
 This page is long. Here are some links to the main sections:

docs/Quick Reference.md

@@ -8,6 +8,8 @@ aliases:
 
 This table summarizes the filters and other options available inside a `tasks` block.
 
+<!-- NEW_QUERY_INSTRUCTION_EDIT_REQUIRED -->
+
 | [[Filters]]                                                                                                                                                                                                                                                                                                                                           | [[Sorting\|Sort]]                           | [[Grouping\|Group]]    | [[Layout\|Display]]    | [[About Scripting\|Scripting]]                                                                                                 |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | **[[Filters#Filters for Dates in Tasks\|Status]]**                                                                                                                                                                                                                                                                                                    |                                             |                        |                        |                                                                                                                                |

docs/Reference/Task Formats/Dataview Format.md

@@ -83,6 +83,8 @@ These samples demonstrate all the fields supported by the Tasks plugin's parsing
 >
 > Tasks also reads dataview fields in parentheses: `(...)`.
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 ### Dataview Format for Dates
 
 These names agree with the same fields in [dataview's documentation](https://blacksmithgu.github.io/obsidian-dataview/annotation/metadata-tasks/#field-shorthands).

docs/Reference/Task Formats/Tasks Emoji Format.md

@@ -8,6 +8,8 @@ publish: true
 
 These samples demonstrate all the fields supported by the Tasks plugin's parsing of its own emoji signifiers.
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
 ## Tasks Emoji Format for Dates
 
 ```markdown

docs/Scripting/Task Properties.md

@@ -18,6 +18,8 @@ In a growing number of locations, Tasks allows programmatic/scripting access to
 
 This page documents all the available pieces of information in Tasks that you can access.
 
+<!-- NEW_TASK_FIELD_EDIT_REQUIRED - Add a note in the relevant bullet list, to record when the new field was added. (No need to add a new table row manually here.) -->
+
 ## Values for Task Statuses
 
 For more information, including adding your own customised statuses, see [[Statuses]].

src/Commands/CreateOrEditTaskParser.ts

@@ -74,6 +74,7 @@ export const taskFromLine = ({ line, path }: { line: string; path: string }): Ta
         console.error('Tasks: Cannot create task on line:', line);
 
         return new Task({
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             status: Status.TODO,
             description: '',
             // We don't need the location fields except file to edit here in the editor.
@@ -109,6 +110,7 @@ export const taskFromLine = ({ line, path }: { line: string; path: string }): Ta
     }
 
     return new Task({
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         status,
         description,
         // We don't need the location fields except file to edit here in the editor.

src/Query/FilterParser.ts

@@ -34,6 +34,7 @@ import { BacklinkField } from './Filter/BacklinkField';
 // When adding new fields keep this order in mind, putting fields that are more specific before fields that
 // may contain them, and keep BooleanField last.
 export const fieldCreators: EndsWith<BooleanField> = [
+    // NEW_QUERY_INSTRUCTION_EDIT_REQUIRED
     () => new StatusNameField(), // status.name is before status, to avoid ambiguity
     () => new StatusTypeField(), // status.type is before status, to avoid ambiguity
     () => new StatusField(),

src/Suggestor/Suggestor.ts

@@ -17,6 +17,7 @@ export function makeDefaultSuggestionBuilder(
     symbols: DefaultTaskSerializerSymbols,
     maxGenericSuggestions: number /** See {@link DEFAULT_MAX_GENERIC_SUGGESTIONS} */,
 ): SuggestionBuilder {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     const datePrefixRegex = [symbols.startDateSymbol, symbols.scheduledDateSymbol, symbols.dueDateSymbol].join('|');
     /*
      * Return a list of suggestions, either generic or more fine-grained to the words at the cursor.
@@ -68,6 +69,7 @@ function addTaskPropertySuggestions(
 
     const genericSuggestions: SuggestInfo[] = [];
 
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     if (!line.includes(symbols.dueDateSymbol))
         genericSuggestions.push({
             displayText: `${symbols.dueDateSymbol} due date`,

src/Task.ts

@@ -119,6 +119,7 @@ interface TaskComponents {
  * @class Task
  */
 export class Task {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     public readonly status: Status;
     public readonly description: string;
     public readonly indentation: string;
@@ -152,6 +153,7 @@ export class Task {
     private _urgency: number | null = null;
 
     constructor({
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         status,
         description,
         taskLocation,
@@ -169,6 +171,7 @@ export class Task {
         originalMarkdown,
         scheduledDateIsInferred,
     }: {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         status: Status;
         description: string;
         taskLocation: TaskLocation;
@@ -186,6 +189,7 @@ export class Task {
         originalMarkdown: string;
         scheduledDateIsInferred: boolean;
     }) {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         this.status = status;
         this.description = description;
         this.indentation = indentation;
@@ -700,6 +704,8 @@ export class Task {
      * @param other
      */
     public identicalTo(other: Task) {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
+
         // Based on ideas from koala. AquaCat and javalent in Discord:
         // https://discord.com/channels/686053708261228577/840286264964022302/996735200388186182
         // and later.

src/TaskFieldRenderer.ts

@@ -124,6 +124,7 @@ export class FieldLayoutDetail {
 }
 
 export const FieldLayoutDetails: { [c in TaskLayoutComponent]: FieldLayoutDetail } = {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     createdDate: new FieldLayoutDetail('task-created', 'taskCreated', FieldLayoutDetail.dateAttributeCalculator),
     dueDate: new FieldLayoutDetail('task-due', 'taskDue', FieldLayoutDetail.dateAttributeCalculator),
     startDate: new FieldLayoutDetail('task-start', 'taskStart', FieldLayoutDetail.dateAttributeCalculator),

src/TaskLayout.ts

@@ -20,6 +20,7 @@ export class LayoutOptions {
 }
 
 export type TaskLayoutComponent =
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     | 'description'
     | 'priority'
     | 'recurrenceRule'
@@ -37,6 +38,7 @@ export type TaskLayoutComponent =
  */
 export class TaskLayout {
     public defaultLayout: TaskLayoutComponent[] = [
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         'description',
         'priority',
         'recurrenceRule',
@@ -66,6 +68,7 @@ export class TaskLayout {
         // Remove components from the layout according to the task options. These represent the existing task options,
         // so some components (e.g. the description) are not here because there are no layout options to remove them.
         const componentsToHideAndGenerateClasses: [boolean, TaskLayoutComponent][] = [
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             [this.options.hidePriority, 'priority'],
             [this.options.hideRecurrenceRule, 'recurrenceRule'],
             [this.options.hideCreatedDate, 'createdDate'],

src/TaskLineRenderer.ts

@@ -314,6 +314,7 @@ export class TaskLineRenderer {
             const tooltip = element.createDiv();
             tooltip.addClasses(['tooltip', 'pop-up']);
 
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             if (task.recurrence) {
                 const recurrenceDiv = tooltip.createDiv();
                 recurrenceDiv.setText(`${recurrenceSymbol} ${task.recurrence.toText()}`);

src/TaskSerializer/DataviewTaskSerializer.ts

@@ -59,6 +59,7 @@ function toInlineFieldRegex(innerFieldRegex: RegExp): RegExp {
  *   [Dataview]{@link https://github.com/blacksmithgu/obsidian-dataview}
  */
 export const DATAVIEW_SYMBOLS = {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     prioritySymbols: {
         Highest: 'priority:: highest',
         High: 'priority:: high',

src/TaskSerializer/DefaultTaskSerializer.ts

@@ -12,6 +12,7 @@ import type { TaskDetails, TaskSerializer } from '.';
  * @interface DefaultTaskSerializerSymbols
  */
 export interface DefaultTaskSerializerSymbols {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     readonly prioritySymbols: {
         Highest: string;
         High: string;
@@ -42,6 +43,7 @@ export interface DefaultTaskSerializerSymbols {
  * Uses emojis to concisely convey meaning
  */
 export const DEFAULT_SYMBOLS: DefaultTaskSerializerSymbols = {
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     prioritySymbols: {
         Highest: '🔺',
         High: '⏫',
@@ -92,6 +94,7 @@ export class DefaultTaskSerializer implements TaskSerializer {
      */
     public componentToString(task: Task, layout: TaskLayout, component: TaskLayoutComponent) {
         const {
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             prioritySymbols,
             startDateSymbol,
             createdDateSymbol,
@@ -102,6 +105,7 @@ export class DefaultTaskSerializer implements TaskSerializer {
         } = this.symbols;
 
         switch (component) {
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             case 'description':
                 return task.description;
             case 'priority': {
@@ -195,6 +199,7 @@ export class DefaultTaskSerializer implements TaskSerializer {
         // Keep matching and removing special strings from the end of the
         // description in any order. The loop should only run once if the
         // strings are in the expected order after the description.
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         let matched: boolean;
         let priority: Priority = Priority.None;
         let startDate: Moment | null = null;
@@ -213,6 +218,7 @@ export class DefaultTaskSerializer implements TaskSerializer {
         const maxRuns = 20;
         let runs = 0;
         do {
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             matched = false;
             const priorityMatch = line.match(TaskFormatRegularExpressions.priorityRegex);
             if (priorityMatch !== null) {
@@ -295,6 +301,7 @@ export class DefaultTaskSerializer implements TaskSerializer {
         // to actually have the description 'Do something #tag1 #tag2'
         if (trailingTags.length > 0) line += ' ' + trailingTags;
 
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         return {
             description: line,
             priority,

src/TaskSerializer/index.ts

@@ -11,6 +11,7 @@ type Writeable<T> = { -readonly [P in keyof T]: T[P] };
 export type TaskDetails = Writeable<
     Pick<
         Task,
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         | 'description'
         | 'priority'
         | 'startDate'

src/ui/EditTask.svelte

@@ -15,6 +15,7 @@
     export let statusOptions: Status[];
 
     const {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         prioritySymbols,
         recurrenceSymbol,
         startDateSymbol,
@@ -24,6 +25,7 @@
 
     let descriptionInput: HTMLTextAreaElement;
     let editableTask: {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         description: string;
         status: Status;
         priority: 'none' | 'lowest' | 'low' | 'medium' | 'high' | 'highest';
@@ -184,6 +186,7 @@
     $: formIsValid = isDueDateValid && isRecurrenceValid && isScheduledDateValid && isStartDateValid && isDescriptionValid;
     $: isDescriptionValid = editableTask.description.trim() !== '';
 
+    // NEW_TASK_FIELD_EDIT_REQUIRED
     $: {
         editableTask.startDate = doAutocomplete(editableTask.startDate);
         parsedStartDate = parseTypedDateForDisplayUsingFutureDate('start', editableTask.startDate);
@@ -255,6 +258,7 @@
         }
 
         editableTask = {
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             description,
             status: task.status,
             priority,
@@ -300,6 +304,7 @@
     }
 
     const _onSubmit = () => {
+        // NEW_TASK_FIELD_EDIT_REQUIRED
         let description = editableTask.description.trim();
         if (addGlobalFilterOnSave) {
             description = GlobalFilter.getInstance().prependTo(description);
@@ -343,6 +348,7 @@
         }
 
         const updatedTask = new Task({
+            // NEW_TASK_FIELD_EDIT_REQUIRED
             ...task,
             description,
             status: editableTask.status,
@@ -364,6 +370,8 @@
 
 <div class="tasks-modal">
     <form on:submit|preventDefault={_onSubmit} class:with-accesskeys="{withAccessKeys}">
+        <!-- NEW_TASK_FIELD_EDIT_REQUIRED -->
+
         <!-- --------------------------------------------------------------------------- -->
         <!--  Description  -->
         <!-- --------------------------------------------------------------------------- -->