docs: add comparison table for mut vs ref parameters

[avorylli]

Summary

Added a structured comparison list explaining the key differences between mut and ref function parameters in the Parameters section. The comparison clarifies three critical aspects: how changes propagate to the caller, call syntax requirements, and the intended purpose of each modifier.

---

Type of change

Please check one:

• Bug fix (fixes incorrect behavior)
• New feature
• Performance improvement
• Documentation change with concrete technical impact
• Style, wording, formatting, or typo-only change

⚠️ Note:
To keep maintainer workload sustainable, we generally do not accept PRs that
are only minor wording, grammar, formatting, or style changes.
Such PRs may be closed without detailed review.

---

Why is this change needed?

The documentation previously explained mut and ref parameters separately without a clear side-by-side comparison. While the variables.adoc page provides better structure, the functions.adoc page lacked explicit comparison, making it harder for readers to understand when to use each modifier and what the practical differences are.

The absence of a comparison table/list created a gap where developers had to piece together information from multiple paragraphs, potentially leading to confusion about:

• Whether changes to mut parameters affect the caller (they don't)
• The syntax requirements for calling functions with ref parameters
• The semantic difference between local mutability (mut) and input/output parameters (ref)

---

What was the behavior or documentation before?

The Parameters section explained mut and ref modifiers in separate paragraphs:

• mut was described as creating a mutable variable that can be modified in the function
• ref was described as simulating a reference that affects the caller's value

However, there was no explicit comparison showing:

• The difference in caller behavior
• The difference in call syntax
• The difference in intended use cases

The only hint was the statement "These can be either mut or ref (not both)" without explaining why they're mutually exclusive or what makes them different.

---

What is the behavior or documentation after?

The documentation now includes a structured comparison list with three key points:

1. Changes in caller - Explicitly states that mut changes are local while ref changes affect the caller
2. Call syntax - Clarifies that mut uses regular expressions while ref requires the ref keyword with a mutable variable
3. Purpose - Distinguishes local mutability (mut) from input/output parameters (ref)

Additionally, a note clarifies that ref parameters are implicitly mutable and cannot be combined with mut, explaining the mutual exclusivity mentioned earlier.

The format follows the same style used elsewhere in the documentation (e.g., the "Snapshots vs references" section in snapshot-type.adoc).

---

Related issue or discussion (if any)

---

Additional context

This change improves the documentation by providing a quick reference for developers choosing between mut and ref parameters. The comparison format is consistent with other comparison sections in the Cairo documentation, maintaining stylistic consistency across the reference manual.

The information was already present in variables.adoc, but having it in functions.adoc as well improves discoverability since developers reading about function parameters will find the comparison in the same section without needing to cross-reference other pages.

[reviewable-StarkWare]

This change is 

[orizi]

@orizi made 1 comment.
Reviewable status: 0 of 1 files reviewed, 1 unresolved discussion (waiting on @avorylli).

---

docs/reference/src/components/cairo/modules/language_constructs/pages/functions.adoc line 81 at r1 (raw file):

* **Purpose** — `mut` parameters: provide local mutability within the function. `ref` parameters: enable input/output parameters that modify the caller's variable.

Note that `ref` parameters are implicitly mutable and cannot be combined with the `mut` modifier on the same parameter.

limit lines to 100 chars.

Code quote:

The key differences between `mut` and `ref` parameters:

* **Changes in caller** — `mut` parameters: changes are local to the function and do not affect the caller's variable. `ref` parameters: changes affect the variable in the caller function.
* **Call syntax** — `mut` parameters: passed as regular expressions. `ref` parameters: must be passed using the `ref` keyword with a mutable variable.
* **Purpose** — `mut` parameters: provide local mutability within the function. `ref` parameters: enable input/output parameters that modify the caller's variable.

Note that `ref` parameters are implicitly mutable and cannot be combined with the `mut` modifier on the same parameter.