Adds associated types documentation. (FuelLabs#5128)

## Description

Adds to the Sway book a new entry for associated types explaining what
they are and how they can be used.

Adds associated types to reference docs.

## Checklist

- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.

---------

Co-authored-by: Joshua Batty <[email protected]>

docs/book/src/SUMMARY.md

@@ -41,6 +41,7 @@
   - [Advanced Types](./advanced/advanced_types.md)
   - [Generic Types](./advanced/generic_types.md)
   - [Traits](./advanced/traits.md)
+  - [Associated Types](./advanced/associated_types.md)
   - [Generics and Trait Constraints](./advanced/generics_and_trait_constraints.md)
   - [Assembly](./advanced/assembly.md)
 - [Common Collections](./common-collections/index.md)

docs/book/src/advanced/associated_types.md

@@ -0,0 +1,68 @@
+# Associated Types
+
+Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete
+implementations of that trait. These associated types are used to specify the return types of trait methods or to
+define type relationships within the trait.
+
+Associated types are a powerful feature of Sway's trait system, enabling generic programming and abstraction over
+types. They help improve code clarity and maintainability by allowing you to define generic traits without committing
+to specific types.
+
+## Declaring Associated Types
+
+Associated types are declared within a trait using the type keyword. Here's the syntax for declaring an associated type:
+
+```sway
+trait MyTrait {
+    type AssociatedType;
+}
+```
+
+## Implementing Associated Types
+
+Concrete implementations of a trait with associated types must provide a specific type for each associated type
+defined in the trait. Here's an example of implementing a trait with an associated type:
+
+```sway
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+    type AssociatedType = u32; // Implementing the associated type with u32
+}
+```
+
+In this example, `MyStruct` implements `MyTrait` and specifies that the associated type `AssociatedType` is `u32`.
+
+## Using Associated Types
+
+Associated types are used within trait methods or where the trait is used as a bound for generic functions or
+structs. You can use the associated type like any other type. Here's an example:
+
+```sway
+trait MyTrait {
+    type AssociatedType;
+    
+    fn get_value(self) -> Self::AssociatedType;
+}
+
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+    type AssociatedType = u32;
+
+    fn get_value(self) -> Self::AssociatedType {
+        42
+    }
+}
+```
+
+In this example, `get_value` is a trait method that returns an associated type `AssociatedType`.
+
+## Use Cases
+
+Associated types are particularly useful in scenarios where you want to define traits that work with different
+types of data structures or abstractions, allowing the implementor to specify the concrete types. Some common use cases include:
+
+- Collections: Traits for generic collections that allow users to specify the type of elements.
+- Iterator Patterns: Traits for implementing iterators with varying element types.
+- Serialization and Deserialization: Traits for serializing and deserializing data with different data formats.

docs/book/src/advanced/index.md

@@ -5,5 +5,6 @@ Advanced concepts.
 - [Advanced Types](./advanced_types.md)
 - [Generic Types](./generic_types.md)
 - [Traits](./traits.md)
+- [Associated Types](./associated_types.md)
 - [Generics and Trait Constraints](./generics_and_trait_constraints.md)
 - [Assembly](./assembly.md)

docs/book/src/advanced/traits.md

@@ -88,6 +88,7 @@ Traits can declare different kinds of associated items in their interface surfac
 
 - [Functions](#associated-functions)
 - [Constants](#associated-constants)
+- [Types](#associated-types)
 
 ### Associated functions
 
@@ -119,6 +120,20 @@ trait Trait {
 
 Check the `associated consts` section on [constants](../basics/constants.md) page.
 
+### Associated types
+
+Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete
+implementations of that trait. These associated types are used to specify the return types of trait methods or to
+define type relationships within the trait.
+
+```sway
+trait MyTrait {
+    type AssociatedType;
+}
+```
+
+Check the `associated types` section on [associated types](./associated_types.md) page.
+
 ## Use Cases
 
 ### Custom Types (structs, enums)

docs/reference/src/code/language/traits/associated-types/.gitignore

@@ -0,0 +1,2 @@
+out
+target

docs/reference/src/code/language/traits/associated-types/Forc.lock

@@ -0,0 +1,3 @@
+[[package]]
+name = 'associated-consts'
+source = 'member'

docs/reference/src/code/language/traits/associated-types/Forc.toml

@@ -0,0 +1,8 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "lib.sw"
+license = "Apache-2.0"
+name = "associated-types"
+implicit-std = false
+
+[dependencies]

docs/reference/src/code/language/traits/associated-types/src/lib.sw

@@ -0,0 +1,26 @@
+script;
+
+trait TypeTrait {
+    type T;
+
+    fn method(self, s1: Self::T) -> Self::T;
+}
+
+struct Struct {}
+
+struct Struct2 {}
+
+impl TypeTrait for Struct2 {
+  type T = Struct;
+
+  fn method(self, s1: Self::T) -> Self::T {
+    s1
+  }
+}
+
+fn main() -> u32 {
+  Struct2{}.method(Struct{});
+
+  1
+}
+

docs/reference/src/documentation/language/traits/index.md

@@ -17,6 +17,7 @@ Associated items come in two varieties:
 
 - [Functions](#associated-functions)
 - [Constants](#associated-constants)
+- [Types](#associated-types)
 
 All traits define an implicit type parameter `Self` that refers to "the type that is implementing this interface".
 Traits may also contain additional type parameters. These type parameters, including `Self`, may be constrained by
@@ -39,10 +40,22 @@ The identifier is the name of the constant used in the path. The type is the typ
 
 An *associated constant definition* defines a constant associated with a type.
 
-### Examples
+### Associated constants examples
 
 ```sway
 {{#include ../../../code/language/traits/associated-consts/src/lib.sw}}
 ```
 
 Associated constants may omit the equals sign and expression to indicate implementations must define the constant value.
+
+## Associated types
+
+Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete
+implementations of that trait. These associated types are used to specify the return types of trait methods or to
+define type relationships within the trait.
+
+### Associated types examples
+
+```sway
+{{#include ../../../code/language/traits/associated-types/src/lib.sw}}
+```