Skip to content

Conversation

@moble
Copy link
Contributor

@moble moble commented Dec 1, 2025

I've always found the documentation of operators a little disjointed and incomplete; this PR aims to improve the situation.

  • Add missing items to the precedence table
    • Adjoint operator goes after :: and before exponentiation
    • Juxtaposition of numeric literals goes after unary operators and before bitshifts
    • Arrows go between || and ?
    • New footnote explains exceptions to exponentiation precedence
    • New footnote explains non-associativity of comparisons, but notes chaining
  • Add more complete lists of operators
    • Include all operators defined in Base
    • Include operators that are available but not defined in Base, set off by parentheses
  • Operator suffixes
    • Note that new operators can be defined with suffixes
    • Explain what those prefixes are
    • Show an example
  • Provide some links between disjoint pages

@inkydragon inkydragon added the docs This change adds or pertains to documentation label Dec 1, 2025
@moble moble force-pushed the patch-2 branch 2 times, most recently from b39e988 to d46161e Compare December 1, 2025 16:17
moble and others added 5 commits December 3, 2025 08:52
- Add adjoint operator to the precedence table at correct precedence
  level between :: and exponentiation
- Explain exceptions to exponentiation precedence
- Include implicit multiplication by juxtaposition of numeric literals in
  precedence table
- Include arrows in precedence table
- Note that comparison operators can be chained with undefined evaluation
  order
- Explain that operators can be used in both infix and functional notation
- Note that new operators can be defined with suffixes, and show an example
@moble
Copy link
Contributor Author

moble commented Dec 3, 2025

Given that the documentation previously said that a space was required in expressions like the +ᵃx discussed above, I guess we would argue that just parsing it as +ᵃ x is actually a bug, which can be fixed by modifying the parser. As such, I don't want to weaken that language, so I've reverted my change to keep the stronger language.

@moble moble requested a review from stevengj December 16, 2025 18:58
@Bhupendra-glitch
Copy link

hello @moble @stevengj
thanks for working on this — this is a really helpful cleanup of the operator docs.

I’ve been reading through the changes and I’m interested in contributing here as well. In particular, I’d like to help by adding a few concrete examples to clarify operator suffixes and chaining behavior, and double-checking that the precedence/associativity descriptions match actual Julia behavior.

Let me know if you’d prefer examples in a specific section or if there are other gaps you’d like help filling. Happy to open a small follow-up commit if that’s useful.

@moble
Copy link
Contributor Author

moble commented Jan 2, 2026

@Bhupendra-glitch Thanks! I'm hoping that this PR could be merged soon, so I think it makes more sense to open that as a separate PR. Feel free to ping me on it!

@stevengj Does this look ready to go to you?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs This change adds or pertains to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants