From e3767f5a44e6161cedbfd4bbb83dbbd2615cda4b Mon Sep 17 00:00:00 2001
From: wixoaGit <wixoag@gmail.com>
Date: Sun, 16 Mar 2025 01:38:32 -0400
Subject: [PATCH] Some list documentation

---
 content/objects/list/proc/add.md  | 30 ++++++++++++++++++++++++++++--
 content/objects/list/proc/copy.md | 15 ++++++++++++++-
 content/objects/list/proc/cut.md  | 13 ++++++++++++-
 content/objects/list/proc/find.md | 16 +++++++++++++++-
 content/objects/list/var/len.md   | 20 +++++++++++++++++++-
 5 files changed, 88 insertions(+), 6 deletions(-)

diff --git a/content/objects/list/proc/add.md b/content/objects/list/proc/add.md
index e0dc4fca5..61637979f 100644
--- a/content/objects/list/proc/add.md
+++ b/content/objects/list/proc/add.md
@@ -2,5 +2,31 @@
 title = "Add"
 slug = "Add" # AUTOGEN FIELD
 [[extra.args]]
-name = "Item1" # AUTOGEN STATIC
-+++
\ No newline at end of file
+name = "Item1, Item2, ..."
+description = "One or more values to add"
++++
+
+Adds a value, or multiple values, to the list.
+
+```dm
+var/list/L = list(1, 2)
+
+L.Add(3)
+world.log << json_encode(L) // "[1,2,3]"
+
+L.Add(4, 5)
+world.log << json_encode(L) // "[1,2,3,4,5]"
+```
+
+If any of the values are another list then the contents of that list will be added rather than the list itself.
+
+```dm
+var/list/L1 = list(1, 2)
+var/list/L2 = list(3, 4)
+
+L1.Add(L2)
+
+// "[1,2,3,4]"
+// NOT "[1,2,[3,4]]"
+world.log << json_encode(L1)
+```
\ No newline at end of file
diff --git a/content/objects/list/proc/copy.md b/content/objects/list/proc/copy.md
index d5128ebbd..785e05419 100644
--- a/content/objects/list/proc/copy.md
+++ b/content/objects/list/proc/copy.md
@@ -4,7 +4,20 @@ slug = "Copy" # AUTOGEN FIELD
 [[extra.args]]
 name = "Start" # AUTOGEN STATIC
 default_value = "1" # AUTOGEN FIELD
+description = "Index of the first element to be included in the copy"
 [[extra.args]]
 name = "End" # AUTOGEN STATIC
 default_value = "0" # AUTOGEN FIELD
-+++
\ No newline at end of file
+description = "Index past the last element to be included in the copy, or 0 for the last element"
+[extra.return]
+description = "A shallow copy of the list"
++++
+
+Returns a new shallow copy of the list.
+
+```dm
+var/list/L1 = list(1, 2, 3)
+var/list/L2 = L1.Copy(2)
+
+world.log << json_encode(L2) // "[2,3]"
+```
\ No newline at end of file
diff --git a/content/objects/list/proc/cut.md b/content/objects/list/proc/cut.md
index 415da111a..56d0f5d7a 100644
--- a/content/objects/list/proc/cut.md
+++ b/content/objects/list/proc/cut.md
@@ -4,7 +4,18 @@ slug = "Cut" # AUTOGEN FIELD
 [[extra.args]]
 name = "Start" # AUTOGEN STATIC
 default_value = "1" # AUTOGEN FIELD
+description = "Index of the first element to be cut from the list"
 [[extra.args]]
 name = "End" # AUTOGEN STATIC
 default_value = "0" # AUTOGEN FIELD
-+++
\ No newline at end of file
+description = "Index past the last element to be cut from the list, or 0 for the last element"
++++
+
+Removes the indicated elements from the list.
+
+```dm
+var/list/L = list(1, 2, 3, 4)
+L.Cut(2, 4)
+
+world.log << json_encode(L) // "[1,4]"
+```
\ No newline at end of file
diff --git a/content/objects/list/proc/find.md b/content/objects/list/proc/find.md
index 32790b1c2..8238ceb3d 100644
--- a/content/objects/list/proc/find.md
+++ b/content/objects/list/proc/find.md
@@ -6,7 +6,21 @@ name = "Elem" # AUTOGEN STATIC
 [[extra.args]]
 name = "Start" # AUTOGEN STATIC
 default_value = "1" # AUTOGEN FIELD
+description = "Index of the first element to be included in the search"
 [[extra.args]]
 name = "End" # AUTOGEN STATIC
 default_value = "0" # AUTOGEN FIELD
-+++
\ No newline at end of file
+description = "Index past the last element to be included in the search, or 0 for the last element"
+[extra.return]
+type = "num"
+description = "The index of the found element, or 0"
++++
+
+Search for the given item in the list. If any values in the list are equal, this will return its index. Otherwise it will return 0.
+
+```dm
+var/list/L = list(10, 20, 30, 20)
+
+// Will return the first instance of 20
+world.log << L.Find(20) // 2
+```
\ No newline at end of file
diff --git a/content/objects/list/var/len.md b/content/objects/list/var/len.md
index 33df28c3f..bf9716468 100644
--- a/content/objects/list/var/len.md
+++ b/content/objects/list/var/len.md
@@ -3,4 +3,22 @@ title = "len"
 [extra]
 default_value = "" # AUTOGEN FIELD
 is_override = false # AUTOGEN FIELD
-+++
\ No newline at end of file
++++
+
+The length of the list. Accessing this gives you the amount of values the list contains.
+
+Changing this value resizes the list, which will remove elements beyond the specified length if the list is shrunk, or grow the list with null values.
+
+```dm
+var/list/my_list = list("foo", "bar", "car")
+my_list.len = 2
+
+for(var/element in my_list)
+    world.log << element // "foo", "bar"
+
+var/list/my_other_list = list("foo")
+my_other_list.len = 3
+
+for(var/element in my_list)
+    world.log << isnull(element) // FALSE (0), TRUE (1), TRUE (1)
+```
\ No newline at end of file