[SPARK-59291][STREAMING] Add return tags to the public StateSpec methods

[uros-b]

What changes were proposed in this pull request?

This completes the Scaladoc on the public StateSpec API:

• Adds @return tags to all nine public methods that lacked them:
  • the four StateSpec.function(...) factory overloads (companion object) -- "a new StateSpec for the mapWithState operation";
  • the five builder methods on the abstract class (initialState x2, numPartitions, partitioner, timeout), which return this.type -- "this StateSpec (to allow chaining)".
• Adds the missing @tparam KeyType to the second and fourth StateSpec.function(...) overloads, which previously documented only ValueType / StateType / MappedType.

Scaladoc only; no code changes.

Why are the changes needed?

It completes the Scaladoc for the public StateSpec surface so the generated API docs state what each method returns and document every type parameter. The function factories return a freshly built StateSpec, and the builder methods return the same instance to allow fluent chaining (as in the class example, StateSpec.function(mappingFunction).numPartitions(10)); this closes a small, pre-existing doc gap.

Does this PR introduce any user-facing change?

No. Scaladoc-only; no API or behavior change.

How was this patch tested?

N/A -- documentation-only change. The streaming module compiles cleanly.

Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.8)

[uros-b]

PTAL @HyukjinKwon @srowen

[uros-b]

soft ping here ^^

[dongjoon-hyun]

Hi, @uros-b . Please be careful in GitHub. Your PR is giving lots of noise to someone who has the valid GitHub Account name like the following. 😄

[dongjoon-hyun]

The doc changes look correct to me: all four function factories build a new StateSpecImpl, and all five builder methods return this.

Could you retitle the PR before merge, e.g. Add return tags to the public StateSpec methods? dev/merge_spark_pr.py strips @ from the PR body but not from the title, so @return would end up in the master commit subject and keep pinging the GitHub user return.

Nit: the 2nd and 4th function overloads are also missing @tparam KeyType. It would be nice to add those here too.

[uros-b]

My apologies to the innocent GitHub user who I tagged here! That's a super cool username, but I couldn't imagine the inbox...😭

[dongjoon-hyun]

Thank you for addressing the comments, @uros-b . The added @tparam KeyType tags look good, and the title no longer contains @.

nit: it would be great to mention the @tparam KeyType additions in the PR description too, since it becomes the commit message.

[uros-b]

Merge Summary:

• merged into master 2dcbadb
• merged into branch-4.x f29cd30

Posted by merge_spark_pr.py

[uros-b]

Thank you @dongjoon-hyun!