From ac7619a6222a2c9bc3b34c6908093490ac02733b Mon Sep 17 00:00:00 2001
From: Aaron Dodson <adodson@google.com>
Date: Tue, 19 Aug 2025 14:56:59 -0700
Subject: [PATCH] chore: Fix documentation generation warnings. (#9325)

* chore: Replace @yields with @returns.

* fix: Update the ESLint config to not require @yields.

* chore: Move docs onto getters.
---
 core/block.ts       | 2 +-
 core/field.ts       | 3 ---
 core/field_input.ts | 6 ++----
 eslint.config.mjs   | 3 ++-
 4 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/core/block.ts b/core/block.ts
index d15700a7e..af44facda 100644
--- a/core/block.ts
+++ b/core/block.ts
@@ -1126,7 +1126,7 @@ export class Block {
   /**
    * Returns a generator that provides every field on the block.
    *
-   * @yields A generator that can be used to iterate the fields on the block.
+   * @returns A generator that can be used to iterate the fields on the block.
    */
   *getFields(): Generator<Field, undefined, void> {
     for (const input of this.inputList) {
diff --git a/core/field.ts b/core/field.ts
index fdcb2d693..3d12880a9 100644
--- a/core/field.ts
+++ b/core/field.ts
@@ -119,9 +119,6 @@ export abstract class Field<T = any>
     return this.size;
   }
 
-  /**
-   * Sets the size of this field.
-   */
   protected set size_(newValue: Size) {
     this.size = newValue;
   }
diff --git a/core/field_input.ts b/core/field_input.ts
index b68530918..97ad0e959 100644
--- a/core/field_input.ts
+++ b/core/field_input.ts
@@ -102,11 +102,9 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
    */
   override SERIALIZABLE = true;
 
-  /**
-   * Sets the size of this field. Although this appears to be a no-op, it must
-   * exist since the getter is overridden below.
-   */
   protected override set size_(newValue: Size) {
+    // Although this appears to be a no-op, it must exist since the getter is
+    // overridden below.
     super.size_ = newValue;
   }
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 0560586cb..744e02b45 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -89,7 +89,8 @@ function buildTSOverride({files, tsconfig}) {
       '@typescript-eslint/no-explicit-any': ['off'],
       // We use this pattern extensively for block (e.g. controls_if) interfaces.
       '@typescript-eslint/no-empty-object-type': ['off'],
-
+      // TSDoc doesn't support @yields, so don't require that we use it.
+      'jsdoc/require-yields': ['off'],
       // params and returns docs are optional.
       'jsdoc/require-param-description': ['off'],
       'jsdoc/require-returns': ['off'],