Macaulay2 / Macaulay2/M2

Document how to declare the typical value of a binary operator method

Open Beginner friendly
#4,523 0 comments 0 reactions 0 assignees View on GitHub
bugs directory Documentation
Dominant language
Macaulay2
Stars
435
Forks
297
Avg merge
4d 20h
Merged PRs (30d)
11

Description

This issue was triaged from [`bugs/dan/0-typical-values`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/0-typical-values), one of the 857 files removed from the pre-GitHub `bugs/` tree by [`d2c8d27826`](https://github.com/Macaulay2/M2/commit/d2c8d27826) and catalogued in [#36](https://github.com/Macaulay2/M2/issues/36). **The commentary below was written by Claude (Claude Opus 5, via Claude Code)**, not by @d-torrance, whose account posted it -- please weigh it accordingly.

### The original file, verbatim

```text
document the typical return value construction used here:

X + X := X => (x,y) -> ...
```

### Where it stands today

Undocumented, and the form works — which is the awkward combination, since a user has no way to learn
about a feature that is fully functional.

### What is missing

`X + X := X => (x,y) -> ...` records a typical value: after it, `typicalValues#(symbol +, X, X)` is `X`,
and the documentation machinery uses that when it renders the method. But:

- **"specifying typical values"** shows only the unary form, `prune Matrix := Matrix => f`;
- **"binary methods"** does not mention it;
- **"installing methods"** does not mention it.

So the binary spelling is nowhere in the manual.

### Related work already done

**PR #3102** (merged) used typical values when documenting *assignment* methods, so `AtomicInt += ZZ`
renders with the right type — evidence that the mechanism is actively relied on, and a natural place
from which to cross-reference the documentation being asked for here.

`open` · disposition `issue` · source of truth: [`bug-triage/catalog.tsv`](https://github.com/d-torrance/M2/blob/bug-triage/bug-triage/catalog.tsv)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the manual sections on “specifying typical values,” “binary methods,” and “installing methods,” then compare the existing unary example with PR #3102’s assignment-method documentation. Document the binary form `X + X := X => (x,y) -> ...` and cross-reference it where appropriate so users can discover how typical values are declared for binary operators.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.