diff --git a/src/public/app/widgets/type_widgets/content_widget.ts b/src/public/app/widgets/type_widgets/content_widget.ts
index c187adb1f..6fd3b360a 100644
--- a/src/public/app/widgets/type_widgets/content_widget.ts
+++ b/src/public/app/widgets/type_widgets/content_widget.ts
@@ -137,6 +137,12 @@ const CONTENT_WIDGETS: Record<string, (typeof NoteContextAwareWidget)[]> = {
     ]
 };
 
+/**
+ * Type widget that displays one or more widgets based on the type of note, generally used for options and other interactive notes such as the backend log.
+ *
+ * One important aspect is that, like its parent {@link TypeWidget}, the content widgets don't receive all events by default and they must be manually added
+ * to the propagation list in {@link TypeWidget.handleEventInChildren}.
+ */
 export default class ContentWidgetTypeWidget extends TypeWidget {
     private $content!: JQuery<HTMLElement>;
     private widget?: BasicWidget;
@@ -177,12 +183,4 @@ export default class ContentWidgetTypeWidget extends TypeWidget {
         }
     }
 
-    async handleEventInChildren<T extends EventNames>(name: T, data: EventData<T>) {
-        if (this.widget && this.widget.handleEvent) {
-            return this.widget.handleEvent(name, data);
-        }
-
-        return super.handleEventInChildren(name, data);
-    }
-
 }
diff --git a/src/public/app/widgets/type_widgets/type_widget.ts b/src/public/app/widgets/type_widgets/type_widget.ts
index 8a78935da..54282795c 100644
--- a/src/public/app/widgets/type_widgets/type_widget.ts
+++ b/src/public/app/widgets/type_widgets/type_widget.ts
@@ -4,6 +4,9 @@ import type FNote from "../../entities/fnote.js";
 import type NoteDetailWidget from "../note_detail.js";
 import type SpacedUpdate from "../../services/spaced_update.js";
 
+/**
+ * The base class for all the note types.
+ */
 export default abstract class TypeWidget extends NoteContextAwareWidget {
 
     spacedUpdate!: SpacedUpdate;
@@ -17,7 +20,7 @@ export default abstract class TypeWidget extends NoteContextAwareWidget {
         return super.doRender();
     }
 
-    doRefresh(note: FNote | null | undefined) {}
+    doRefresh(note: FNote | null | undefined): void | Promise<void> {}
 
     async refresh() {
         const thisWidgetType = (this.constructor as any).getType();
@@ -61,12 +64,20 @@ export default abstract class TypeWidget extends NoteContextAwareWidget {
         }
     }
 
-    // events should be propagated manually to the children widgets
+    /**
+     * {@inheritdoc}
+     *
+     * By default:
+     *
+     * - `activeContextChanged` is intercepted and converted to a `setNoteContext` event to avoid `refresh()`.
+     * - `entitiesReloaded` and `refreshData` are passed as-is.
+     * - any other event is not passed to the children.
+     */
     handleEventInChildren<T extends EventNames>(name: T, data: EventData<T>) {
         if (["activeContextChanged", "setNoteContext"].includes(name)) {
             // won't trigger .refresh();
             return super.handleEventInChildren("setNoteContext", data as EventData<"activeContextChanged">);
-        } else if (name === "entitiesReloaded") {
+        } else if (name === "entitiesReloaded" || name === "refreshData") {
             return super.handleEventInChildren(name, data);
         } else {
             return Promise.resolve();