Update widgets API doc to reflect favorites support

.generator/schemas/v2/openapi.yaml

@@ -82741,7 +82741,12 @@ components:
         definition:
           $ref: "#/components/schemas/WidgetDefinition"
         is_favorited:
-          description: "Will be implemented soon. Currently always returns false."
+          description: |-
+            Whether the current user has favorited this widget. Populated on get,
+            batch_get, update, and search responses; create responses always return
+            `false` because a widget can only be favorited after it exists.
+            Favoriting itself is performed through the shared favorites API, not
+            this service.
           example: false
           type: boolean
         modified_at:
@@ -134588,7 +134593,17 @@ paths:
           - teams_read
   /api/v2/widgets/{experience_type}:
     get:
-      description: Search and list widgets for a given experience type. Supports filtering by widget type, creator, title, and tags, as well as sorting and pagination.
+      description: |-
+        Search and list widgets for a given experience type, with filtering, sorting, and pagination.
+
+        **Response meta** carries totals scoped to the current filter:
+        - `filtered_total` — widgets matching the filter.
+        - `created_by_you_total` — among the matches, how many the current user created.
+        - `favorited_by_you_total` — among the matches, how many the current user has favorited.
+        - `created_by_anyone_total` — total widgets in the experience type, ignoring filters.
+
+        Each returned widget includes `is_favorited` reflecting the current user's favorite status.
+        Favoriting itself is performed through the shared favorites API, not this endpoint.
       operationId: SearchWidgets
       parameters:
         - description: The experience type for the widget.
@@ -134624,8 +134639,14 @@ paths:
           schema:
             type: string
         - description: |-
-            Sort field for the results. Prefix with `-` for descending order.
-            Allowed values: `title`, `created_at`, `modified_at`.
+            Sort field for the results.
+
+            **`title`, `created_at`, `modified_at`** — both ascending and descending are
+            supported. Use the bare field name for ascending (e.g. `sort=title`) or prefix
+            with `-` for descending (e.g. `sort=-modified_at`).
+
+            **`is_favorited`** — returns favorites-first ordering (favorited widgets first,
+            then the rest). Direction is fixed; the `-` prefix is ignored for this field.
           in: query
           name: sort
           schema:

src/main/java/com/datadog/api/client/v2/api/WidgetsApi.java

@@ -618,8 +618,12 @@ public SearchWidgetsOptionalParameters filterTags(String filterTags) {
     /**
      * Set sort.
      *
-     * @param sort Sort field for the results. Prefix with <code>-</code> for descending order.
-     *     Allowed values: <code>title</code>, <code>created_at</code>, <code>modified_at</code>.
+     * @param sort Sort field for the results. <strong><code>title</code>, <code>created_at</code>,
+     *     <code>modified_at</code></strong> — both ascending and descending are supported. Use the
+     *     bare field name for ascending (e.g. <code>sort=title</code>) or prefix with <code>-
+     *     </code> for descending (e.g. <code>sort=-modified_at</code>). <strong><code>is_favorited
+     *     </code></strong> — returns favorites-first ordering (favorited widgets first, then the
+     *     rest). Direction is fixed; the <code>-</code> prefix is ignored for this field.
      *     (optional, default to "-modified_at")
      * @return SearchWidgetsOptionalParameters
      */
@@ -717,8 +721,17 @@ public CompletableFuture<WidgetListResponse> searchWidgetsAsync(
   }
 
   /**
-   * Search and list widgets for a given experience type. Supports filtering by widget type,
-   * creator, title, and tags, as well as sorting and pagination.
+   * Search and list widgets for a given experience type, with filtering, sorting, and pagination.
+   *
+   * <p><strong>Response meta</strong> carries totals scoped to the current filter: - <code>
+   * filtered_total</code> — widgets matching the filter. - <code>created_by_you_total</code> —
+   * among the matches, how many the current user created. - <code>favorited_by_you_total</code> —
+   * among the matches, how many the current user has favorited. - <code>created_by_anyone_total
+   * </code> — total widgets in the experience type, ignoring filters.
+   *
+   * <p>Each returned widget includes <code>is_favorited</code> reflecting the current user's
+   * favorite status. Favoriting itself is performed through the shared favorites API, not this
+   * endpoint.
    *
    * @param experienceType The experience type for the widget. (required)
    * @param parameters Optional parameters for the request.

src/main/java/com/datadog/api/client/v2/model/WidgetAttributes.java

@@ -111,7 +111,10 @@ public WidgetAttributes isFavorited(Boolean isFavorited) {
   }
 
   /**
-   * Will be implemented soon. Currently always returns false.
+   * Whether the current user has favorited this widget. Populated on get, batch_get, update, and
+   * search responses; create responses always return <code>false</code> because a widget can only
+   * be favorited after it exists. Favoriting itself is performed through the shared favorites API,
+   * not this service.
    *
    * @return isFavorited
    */