Merge pull request #249 from onflow/glossary

Edit Glossary article

Author: briandoyle81

docs/language/glossary.mdx

@@ -3,10 +3,13 @@ title: Glossary
 sidebar_position: 26
 ---
 
+This glossary provides clear explanations and code examples for the most important symbols and operators in Cadence. Each entry describes the symbol's purpose, usage, and common scenarios, helping both new and experienced developers quickly understand Cadence syntax.
+
+Use this guide as a handy reference to navigate Cadence's unique features and operator behaviors.
 
 :::tip
 
-Tip: <kbd>CTRL</kbd>/<kbd>⌘</kbd> + <kbd>F</kbd> and type in the symbol or operator you want to look up.
+To search for a term, press <kbd>CTRL</kbd>/<kbd>⌘</kbd> + <kbd>F</kbd> and type in the symbol or operator you want to look up.
 
 :::
 
@@ -16,27 +19,25 @@ The `&` (ampersand) symbol has several uses.
 
 ### Reference
 
-If an expression starts with the `&` (ampersand) symbol, it creates a [reference](./references.mdx).
+If an expression starts with the `&` (ampersand) symbol, it creates a [reference].
 
 ```cadence
 let a: String = "hello"
 let refOfA: &String = &a as &String
 ```
 
-References may also be authorized if the `&` symbol is preceded by `auth` (otherwise the reference is unauthorized).
+References may also be authorized if the `&` symbol is preceded by `auth`. Otherwise, the reference is unauthorized.
 
-Authorized references have the `auth` modifier, along with the set of entitlements to which the reference is authorized,
-i.e. the full syntax is `auth(E, F) &T`, whereas unauthorized references do not have a modifier.
+Authorized references have the `auth` modifier, along with the set of entitlements to which the reference is authorized (i.e., the full syntax is `auth(E, F) &T`, whereas unauthorized references do not have a modifier).
 
 ```cadence
 let a: String = "hello"
 let refOfA: auth(X) &String = &a as auth(X) &String
 ```
 
-### Logical Operator
+### Logical operator
 
-It can be also used as a [logical operator (AND)](./operators/arithmetic-logical-operators.md#logical-operators),
-by appearing twice in succession (i.e. `&&`):
+The `&` (ampersand) symbol can be also used as a [logical operator (AND)], by appearing twice in succession (i.e., `&&`):
 
 ```cadence
 let a = true
@@ -47,11 +48,9 @@ let c = a && b // false
 
 ## `@` (at)
 
-The `@` (at) symbol before a type is used to annotate whether the type is a [resource](./resources.mdx).
+The `@` (at) symbol before a type is used to annotate whether the type is a [resource].
 
-The `@` symbol must appear at the beginning of the type, not inside.
-For example, an array of `NFT`s is `@[NFT]`, not `[@NFT]`.
-This emphasizes the whole type acts like a resource.
+The `@` symbol must appear at the beginning of the type, not inside. For example, an array of `NFT`s is `@[NFT]`, not `[@NFT]`. This emphasizes that the whole type acts like a resource.
 
 ```cadence
 // Declare a resource named `SomeResource`
@@ -69,7 +68,7 @@ resource SomeResource {
 // we use the '@' symbol to reference a resource type
 let a: @SomeResource <- create SomeResource(value: 0)
 
-// also in functions declarations
+// also in function declarations
 access(all)
 fun use(resource: @SomeResource) {
     destroy resource
@@ -80,7 +79,7 @@ fun use(resource: @SomeResource) {
 
 The `:` (colon) symbol has several uses.
 
-### Type Declaration
+### Type declaration
 
 If a `:` (colon) follows a variable/constant/function declaration, it is used to declare its type.
 
@@ -94,10 +93,9 @@ fun addOne(x: Int): Int { // return type of Int
 }
 ```
 
-### Ternary Conditional Operator
+### Ternary conditional operator
 
-The `:` (colon) is also be used in [ternary operations](./operators/bitwise-ternary-operators.md#ternary-conditional-operator) to represent the "otherwise" section,
-such as the following:
+The `:` (colon) can also be used in [ternary operations] to represent the "otherwise" section, such as the following:
 
 ```cadence
 let a = 1 > 2 ? 3 : 4
@@ -111,7 +109,7 @@ let a = 1 > 2 ? 3 : 4
 
 The `=` (equals) symbol has several uses.
 
-### Variable Declaration
+### Variable declaration
 
 ```cadence
 let a = 1 // declares a variable `a` with value `1`
@@ -125,9 +123,9 @@ a = 1  // assigns the value `1` to variable `a `
 
 ## `!` (exclamation mark)
 
-The `!` (exclamation mark) symbol has a different effect whether it precedes or succeeds a variable.
+The `!` (exclamation mark) symbol has a different effect depending on whether it precedes or succeeds a variable.
 
-When it immediately **precedes** a boolean-type variable, it negates it.
+When it immediately **precedes** a boolean-type variable, it negates it:
 
 ```cadence
 let a: Bool = true
@@ -136,9 +134,7 @@ let b: Bool = !a
 // b is false
 ```
 
-When it immediately **succeeds** an *optional* variable, it [force-unwraps](./operators/optional-operators.md#force-unwrap-operator-) it.
-Force-unwrapping returns the value inside an optional if it contains a value,
-or panics and aborts the execution if the optional has no value, i.e. the optional value is nil.
+When it immediately **succeeds** an _optional_ variable, it [force unwraps] it. Force unwrapping returns the value inside an optional if it contains a value, or panics and aborts the execution if the optional has no value (i.e., the optional value is nil):
 
 ```cadence
 let a: Int? = nil
@@ -152,17 +148,17 @@ let d: Int = b! // initialized correctly as 3
 
 The `/` (forward slash) symbol has several uses.
 
-### Division Operator
+### Division operator
 
-Inbetween two expressions, the forward slash acts as the [division operator](./operators/arithmetic-logical-operators.md#arithmetic-operators).
+Between two expressions, the forward slash acts as the [division operator]:
 
 ```cadence
 let result = 4 / 2
 ```
 
 ### Path separator
 
-In a [path](./accounts/paths.mdx), the forward slash separates the domain, `storage` or `public`, and the identifier.
+In a [path], the forward slash separates the domain, `storage` or `public`, and the identifier:
 
 ```cadence
 let storagePath = /storage/path
@@ -171,14 +167,12 @@ storagePath.toString()  // is "/storage/path"
 
 ## `<-` (lower than, hyphen) (Move operator)
 
-The [move operator `<-`](./resources.mdx#the-move-operator--) is like the assignment operator `=`,
-but must be used when the value is a [resource](./resources.mdx).
-To make assignment of resources explicit, the move operator `<-` must be used when:
+The [move operator `<-`] is like the assignment operator `=`, but must be used when the value is a [resource]. To make the assignment of resources explicit, the move operator `<-` must be used when the resource is:
 
-- The resource is the initial value of a constant or variable,
-- The resource is moved to a different variable in an assignment,
-- The resource is moved to a function as an argument
-- The resource is returned from a function.
+- the initial value of a constant or variable,
+- moved to a different variable in an assignment,
+- moved to a function as an argument, or
+- returned from a function.
 
 ```cadence
 resource R {}
@@ -188,9 +182,7 @@ let a <- create R() // we instantiate a new resource and move it into a
 
 ## `<-!` (lower than, hyphen, exclamation mark) (Force-assignment move operator)
 
-The [force-assignment move operator `<-!`](./operators/assign-move-force-swap.md#force-assignment-operator--) moves a resource value to an optional variable.
-If the variable is `nil`, the move succeeds.
-If it is not nil, the program aborts.
+The [force-assignment move operator `<-!`] moves a resource value to an optional variable. If the variable is `nil`, the move succeeds. If it is not nil, the program aborts.
 
 ```cadence
 access(all)
@@ -202,12 +194,11 @@ a <-! create R()
 
 ## `<->` (lower than, hyphen, greater than) (Swap operator)
 
-The [swapping operator `<->`](./operators/assign-move-force-swap.md#swapping-operator--) swaps two resource between the variables to the left and right of it.
-
+The [swapping operator `<->`] swaps two resources between the variables to the left and right of it.
 
 ## `+` (plus), `-` (minus), `*` (asterisk), `%` (percentage sign)
 
-These are all typical [arithmetic operators](./operators/arithmetic-logical-operators.md#arithmetic-operators):
+These are all typical [arithmetic operators]:
 
 - Addition: `+`
 - Subtraction: `-`
@@ -220,19 +211,17 @@ The `?` (question mark) symbol has several uses.
 
 ### Optional
 
-If a `?` (question mark) follows a variable/constant, it represents an optional.
-An optional can either have a value or *nothing at all*.
+If a `?` (question mark) follows a variable/constant, it represents an optional. An optional can either have a value or _nothing at all_:
 
 ```cadence
 // Declare a constant which has an optional integer type
 //
 let a: Int? = nil
 ```
 
-### Ternary Conditional Operator
+### Ternary conditional operator
 
-The `?` (question mark) is also be used in [ternary operations](./operators/bitwise-ternary-operators.md#ternary-conditional-operator) to represent the "then" section,
-such as the following:
+The `?` (question mark) can also be used in [ternary operations] to represent the _then_ section, such as the following:
 
 ```cadence
 let a = 1 > 2 ? 3 : 4
@@ -242,12 +231,11 @@ let a = 1 > 2 ? 3 : 4
 //   "otherwise, set a = 4.
 ```
 
-### Nil-Coalescing Operator
+### Nil-coalescing operator
 
-The `?` (question mark) is also used in the [nil-coalescing operator `??`](./operators/optional-operators.md#nil-coalescing-operator-).
+The `?` (question mark) is also used in the [nil-coalescing operator `??`].
 
-It returns the value inside the optional, if the optional contains a value,
-or returns an alternative value if the optional has no value, i.e., the optional value is nil.
+It returns the value inside the optional if the optional contains a value, or returns an alternative value if the optional has no value (i.e., the optional value is nil):
 
 ```cadence
 // Declare a constant which has an optional integer type
@@ -273,24 +261,24 @@ The `_` (underscore) symbol has several uses.
 
 ### Names
 
-The `_` (underscore) can be used in names, e.g. in variables and types.
+The `_` (underscore) can be used in names (e.g., in variables and types):
 
 ```cadence
 let _a = true // used as a variable name
 let another_one = false
 ```
 
-### Number Literals
+### Number literals
 
-The `_` (underscore) can also be used to split up numerical components.
+The `_` (underscore) can also be used to split up numerical components:
 
 ```cadence
 let b = 100_000_000 // used to split up a number (supports all number types, e.g. 0b10_11_01)
 ```
 
-### Argument Labels
+### Argument labels
 
-The `_` (underscore) can also be to indicate that a parameter in a [function](./functions.mdx) has no argument label.
+The `_` (underscore) can also be used to indicate that a parameter in a [function] has no argument label:
 
 ```cadence
 // The special argument label _ is specified for the parameter,
@@ -302,3 +290,19 @@ fun double(_ x: Int): Int {
 
 let result = double(4)
 ```
+
+<!-- Relative links. Will not render on the page -->
+
+[arithmetic operators]: ./operators/arithmetic-logical-operators.md#arithmetic-operators
+[division operator]: ./operators/arithmetic-logical-operators.md#arithmetic-operators
+[force-assignment move operator `<-!`]: ./operators/assign-move-force-swap.md#force-assignment-operator--
+[force unwraps]: ./operators/optional-operators.md#force-unwrap-operator-
+[function]: ./functions.mdx
+[logical operator (AND)]: ./operators/arithmetic-logical-operators.md#logical-operators
+[move operator `<-`]: ./resources.mdx#the-move-operator--
+[nil-coalescing operator `??`]: ./operators/optional-operators.md#nil-coalescing-operator-
+[path]: ./accounts/paths.mdx
+[reference]: ./references.mdx
+[resource]: ./resources.mdx
+[swapping operator `<->`]: ./operators/assign-move-force-swap.md#swapping-operator--
+[ternary operations]: ./operators/bitwise-ternary-operators.md#ternary-conditional-operator