From d84bda837d626f27276b444246610ab02526ba99 Mon Sep 17 00:00:00 2001
From: Meghan <43832670+meghanmae@users.noreply.github.com>
Date: Mon, 26 Aug 2024 08:27:56 -0700
Subject: [PATCH] docs: Update ManyToMany docs (#424)

---
 .../attributes/many-to-many.md                | 52 ++++++++++++++++++-
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/docs/modeling/model-components/attributes/many-to-many.md b/docs/modeling/model-components/attributes/many-to-many.md
index 397ae458b..6adbc2868 100644
--- a/docs/modeling/model-components/attributes/many-to-many.md
+++ b/docs/modeling/model-components/attributes/many-to-many.md
@@ -11,7 +11,7 @@ ViewModel.
 The named specified in the attribute will be used as the name of a collection of the objects on the other side of the relationship in the generated [TypeScript ViewModels](/stacks/disambiguation/view-model.md). 
 
 ## Example Usage
-
+In this example, we have a Person entity and an Appointment entity that share a many-to-many relationship. The PersonAppointment entity serves as the required middle table.
 ``` c#
 public class Person
 {
@@ -22,6 +22,26 @@ public class Person
     [ManyToMany("Appointments")]
     public ICollection<PersonAppointment> PersonAppointments { get; set; }
 }
+
+public class Appointment
+{
+    public int AppointmentId { get; set; }
+    public DateTime AppointmentDate { get; set; }
+
+    [ManyToMany("People")]
+    public ICollection<PersonAppointment> PersonAppointments { get; set; }
+}
+
+public class PersonAppointment
+{
+    public int PersonAppointmentId { get; set; }
+
+    public int PersonId { get; set; }
+    public Person Person { get; set; }
+
+    public int AppointmentId { get; set; }
+    public Appointment Appointment { get; set; }
+}
 ```
 
 ## Properties
@@ -33,4 +53,32 @@ The name of the collection that will contain the set of objects on the other sid
 
 <Prop def="public string FarNavigationProperty { get; set; }" />
 
-The name of the navigation property on the middle entity that points at the far side of the many-to-many relationship. Use this to resolve ambiguities when the middle table of the many-to-many relationship has more than two reference navigation properties on it.
\ No newline at end of file
+The name of the navigation property on the middle entity that points at the far side of the many-to-many relationship. Use this to resolve ambiguities when the middle table of the many-to-many relationship has more than two reference navigation properties on it.
+
+``` c#
+public class Person
+{
+    ...
+    
+    [ManyToMany("Appointments", FarNavigationProperty = nameof(PersonAppointment.Appointment))]
+    public ICollection<PersonAppointment> PersonAppointments { get; set; }
+}
+
+public class Appointment
+{
+    ...
+
+    [ManyToMany("People", FarNavigationProperty = nameof(PersonAppointment.Person))]
+    public ICollection<PersonAppointment> PersonAppointments { get; set; }
+}
+
+public class PersonAppointment
+{
+    ...
+
+    // Adding a third reference navigation property in the middle table requires 
+    // the use of FarNavigationProperty in order to resolve ambiguity.
+    public int WaiverId { get; set; }
+    public Waiver Waiver { get; set; }
+}
+```
\ No newline at end of file