chore: Deprecate internal-only APIs in AggregateExec

[2010YOUY01]

Which issue does this PR close?

• Closes #.

Rationale for this change

AggregateExec::{with_new_limit_options, with_limit_options, limit_options} set a limit hint on an aggregation. This is part of the public API for AggregateExec

It's nearly impossible to use it correctly (see below code explanation) if we see it as a public ExecutionPlan API, however it requires pub because physical optimizer requires it.

// physical optimizer
if tricky_pre_conditions() {
  agg_exec.with_limit_options(k)
}

This PR does:

• Deprecate those API, but it can't get deleted since optimizer requires it. This approach can warn downstreams that this API is unsafe and should not be used directly
• Mark #[doc(hidden)]. That is the usual Rust convention for "public for technical reasons, not for external user": the item is dropped from generated docs (docs.rs)

What changes are included in this PR?

What is the testing strategy for this PR?

Are there any user-facing changes?

Yes, deprecations.

[2010YOUY01]

Not sure if there are better approaches for this case, it we have to do this way, we can later doc this pattern in
https://datafusion.apache.org/contributor-guide/api-health.html

[github-actions]

Thank you for opening this pull request!

Reviewer note: cargo-semver-checks reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch).

Details

     Cloning apache/main
    Building datafusion v55.0.0 (current)
       Built [  42.429s] (current)
     Parsing datafusion v55.0.0 (current)
      Parsed [   0.024s] (current)
    Building datafusion v55.0.0 (baseline)
       Built [  37.990s] (baseline)
     Parsing datafusion v55.0.0 (baseline)
      Parsed [   0.024s] (baseline)
    Checking datafusion v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.391s] 223 checks: 223 pass, 31 skip
     Summary no semver update required
    Finished [  82.407s] datafusion
    Building datafusion-physical-optimizer v55.0.0 (current)
       Built [  25.916s] (current)
     Parsing datafusion-physical-optimizer v55.0.0 (current)
      Parsed [   0.015s] (current)
    Building datafusion-physical-optimizer v55.0.0 (baseline)
       Built [  26.308s] (baseline)
     Parsing datafusion-physical-optimizer v55.0.0 (baseline)
      Parsed [   0.015s] (baseline)
    Checking datafusion-physical-optimizer v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.072s] 223 checks: 223 pass, 31 skip
     Summary no semver update required
    Finished [  53.201s] datafusion-physical-optimizer
    Building datafusion-physical-plan v55.0.0 (current)
       Built [  24.255s] (current)
     Parsing datafusion-physical-plan v55.0.0 (current)
      Parsed [   0.107s] (current)
    Building datafusion-physical-plan v55.0.0 (baseline)
       Built [  24.044s] (baseline)
     Parsing datafusion-physical-plan v55.0.0 (baseline)
      Parsed [   0.106s] (baseline)
    Checking datafusion-physical-plan v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.464s] 223 checks: 222 pass, 1 fail, 0 warn, 31 skip

--- failure type_method_marked_deprecated: type method #[deprecated] added ---

Description:
A type method is now #[deprecated]. Downstream crates will get a compiler warning when using this method.
        ref: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/type_method_marked_deprecated.ron

Failed in:
  method datafusion_physical_plan::aggregates::AggregateExec::with_new_limit_options in /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/aggregates/mod.rs:946
  method datafusion_physical_plan::aggregates::AggregateExec::with_limit_options in /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/aggregates/mod.rs:973
  method datafusion_physical_plan::aggregates::AggregateExec::limit_options in /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/aggregates/mod.rs:986

     Summary semver requires new minor version: 0 major and 1 minor checks failed
    Finished [  50.262s] datafusion-physical-plan
    Building datafusion-proto v55.0.0 (current)
       Built [  34.914s] (current)
     Parsing datafusion-proto v55.0.0 (current)
      Parsed [   0.011s] (current)
    Building datafusion-proto v55.0.0 (baseline)
       Built [  35.213s] (baseline)
     Parsing datafusion-proto v55.0.0 (baseline)
      Parsed [   0.013s] (baseline)
    Checking datafusion-proto v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.074s] 223 checks: 223 pass, 31 skip
     Summary no semver update required
    Finished [  71.417s] datafusion-proto

[codecov-commenter]

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 81.88%. Comparing base (681705e) to head (97e4c7a).

Files with missing lines	Patch %	Lines
...hysical-plan/src/aggregates/grouped_hash_stream.rs	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #25257      +/-   ##
==========================================
- Coverage   81.88%   81.88%   -0.01%     
==========================================
  Files        1133     1133              
  Lines      424522   424522              
  Branches   424522   424522              
==========================================
- Hits       347622   347615       -7     
- Misses      56288    56291       +3     
- Partials    20612    20616       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.