Revise documentation for internal _copy utility

[yebai]

The PR cleans up docs on _copy and adds an overview of _copy's current behaviour for different types

Replacing and closes #760

[github-actions]

Mooncake.jl documentation for PR #762 is available at:
https://chalk-lab.github.io/Mooncake.jl/previews/PR762/

[Copilot]

Pull Request Overview

This PR updates the documentation for the internal _copy utility function, improving clarity and readability. The changes replace verbose technical documentation with a more concise format that focuses on practical examples of current behavior.

• Replaces detailed implementation requirements with warning about internal API status
• Converts extensive code examples to a concise list of type-specific behaviors
• Updates comments in dual.jl and codual.jl to remove redundant "immutable" references

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/utils.jl	Simplifies _copy documentation with warning block and behavior examples
src/dual.jl	Updates comment to remove redundant "immutable" reference
src/codual.jl	Updates comment to remove redundant "immutable" reference

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[github-actions]

Performance Ratio:
Ratio of time to compute gradient and time to compute function.
Warning: results are very approximate! See here for more context.

┌────────────────────────────┬──────────┬──────────┬─────────────┬─────────┬────
│                      Label │   Primal │ Mooncake │ MooncakeFwd │  Zygote │ R ⋯
│                     String │   String │   String │      String │  String │   ⋯
├────────────────────────────┼──────────┼──────────┼─────────────┼─────────┼────
│                   sum_1000 │ 100.0 ns │      1.8 │         1.8 │     1.1 │   ⋯
│                  _sum_1000 │ 941.0 ns │     6.74 │        1.01 │  1480.0 │   ⋯
│               sum_sin_1000 │  6.53 μs │     2.22 │         1.4 │    1.71 │   ⋯
│              _sum_sin_1000 │   5.2 μs │     2.67 │        2.21 │   279.0 │   ⋯
│                   kron_sum │ 273.0 μs │     48.2 │         3.5 │     6.0 │   ⋯
│              kron_view_sum │ 325.0 μs │     42.6 │        3.38 │    11.4 │   ⋯
│      naive_map_sin_cos_exp │  2.12 μs │     2.16 │         1.4 │ missing │   ⋯
│            map_sin_cos_exp │  2.11 μs │     2.43 │        1.44 │    1.47 │   ⋯
│      broadcast_sin_cos_exp │  2.23 μs │     2.27 │        1.38 │    2.36 │   ⋯
│                 simple_mlp │ 198.0 μs │     6.47 │         3.1 │    1.71 │   ⋯
│                     gp_lml │ 241.0 μs │     8.82 │        2.08 │    3.76 │   ⋯
│ turing_broadcast_benchmark │  1.95 ms │     3.83 │        3.04 │ missing │   ⋯
│         large_single_block │ 390.0 ns │     4.42 │        1.98 │  4240.0 │   ⋯
└────────────────────────────┴──────────┴──────────┴─────────────┴─────────┴────
                                                               2 columns omitted

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yebai]

@gdalle, I'd appreciate it if you could take a look at this.

[mhauru]

I have a couple of proposals, but nothing show-stopping, seems fine to me.

[mhauru]

Would it be useful to say something about where _copy gets used? Or something else that would help answer the question of, if I was to implement my own type Foo, what should I make _copy(::Foo) do?

[yebai]

It is a bit awkward to say any more about that for now -- the _copy function is a bit scattered and thus requires some tidy up down the road.

[mhauru]

Might it make sense to document these in the same place where they are implemented? Some of these implementations must live in other files, and could be added as docstrings to the methods that implement them. Less risk of the documentation falling out of sync with the implementation.

[yebai]

That is already done as comments, the point of repeating them here is to have an overview.

[yebai]

Thanks @mhauru -- I addressed your comments.