From 99576570229da137af66d579fb4ba276a57ba07b Mon Sep 17 00:00:00 2001
From: harryob <55142896+harryob@users.noreply.github.com>
Date: Mon, 5 Aug 2024 20:19:34 +0100
Subject: [PATCH] expands readme, touches on [extra] toml section

---
 README.md                                 | 13 +++++++++++++
 content/objects/area/var/layer.md         |  2 +-
 content/objects/atom/movable/proc/move.md |  2 +-
 content/objects/atom/proc/cross.md        |  3 ++-
 templates/macros.html                     |  6 ++++--
 5 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a42a21a32..5ccc759eb 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,19 @@ And these frontmatter fields are automatically populated, and should not be chan
   - Override status (`is_override`)
   - Unimplemented status (`od_unimplemented`)
 
+## [extra] Documentation
+
+Zola allows us to put arbitrary TOML under the [extra] section, which we do for the various page types. This includes the fields that editors can set, not the ones pulled from DMStandard (above).
+
+- Objects:
+  - `parent_type` - This allows us to construct the parent types for any object - such as /mob going to /atom/movable, then /atom, then /datum.
+- Procs:
+  - `return_type_desc` - This allows us to add extra information about the return type - for example, what specific return types mean. It can also be used to document the return type if not pulled from DMStandard.
+  - `[[args.description]]` - We can document individual arguments to procs with the `description` field. These edits will not be removed by the Autodocumentation tool.
+- Vars:
+  - `default_value_desc` - This allows us to add extra information about the default value that this variable is set to.
+
+
 ## Available markdown formatting
 
 Zola uses [CommonMark](https://commonmark.org/) and the [pulldown-cmark](https://github.com/pulldown-cmark/pulldown-cmark#pulldown-cmark) parser.
diff --git a/content/objects/area/var/layer.md b/content/objects/area/var/layer.md
index e17424831..d90be2a31 100644
--- a/content/objects/area/var/layer.md
+++ b/content/objects/area/var/layer.md
@@ -2,6 +2,6 @@
 title = "layer"
 [extra]
 default_value = "1"
-default_value_text = "(AREA_LAYER)"
+default_value_desc = "(AREA_LAYER)"
 is_override = true
 +++
\ No newline at end of file
diff --git a/content/objects/atom/movable/proc/move.md b/content/objects/atom/movable/proc/move.md
index 1d3065b9f..27bd41b78 100644
--- a/content/objects/atom/movable/proc/move.md
+++ b/content/objects/atom/movable/proc/move.md
@@ -2,7 +2,7 @@
 title = "Move"
 
 [extra]
-return_val = """1 on success
+return_type_desc = """1 on success
 0 on failure
 Number of pixels moved for a successful slide.
 """
diff --git a/content/objects/atom/proc/cross.md b/content/objects/atom/proc/cross.md
index a69aa8686..567316db8 100644
--- a/content/objects/atom/proc/cross.md
+++ b/content/objects/atom/proc/cross.md
@@ -2,7 +2,8 @@
 title = "Cross"
 
 [extra]
-return_val = """1 to allow movement
+return_type = "num"
+return_type_desc = """1 to allow movement
 0 to prevent movement
 """
 
diff --git a/templates/macros.html b/templates/macros.html
index 53a128a89..4b268df49 100644
--- a/templates/macros.html
+++ b/templates/macros.html
@@ -314,12 +314,14 @@ <h1 class="title text-3xl">
 
     {{ macros::render_proc_args_long(page=page) }}
 
+    {% if page.extra.return_type or page.extra.return_type_desc %}
     <div class="border-l-2 border-gray-500 pl-3">
     <div class="text-xl">Returns:</div> 
     <div class="pl-5">
-        {{ page.extra.return_val | default(value="null") | linebreaksbr | markdown | safe }}
+        {% if page.extra.return_type %}{{ page.extra.return_type }}{% endif %}{% if page.extra.return_type and page.extra.return_type_desc %}: {% endif %}{% if page.extra.return_type_desc %} {{ page.extra.return_type_desc | linebreaksbr | markdown | safe }}{% endif %}
     </div> 
     </div>
+    {% endif %}
 
     {% if page.extra.od_unimplemented %}
     {{ sc::render_callout(color="#f87171", 
@@ -357,7 +359,7 @@ <h1 class="title text-3xl code-title">
     {% if page.extra.default_value %}
     <div class="border-l-2 border-gray-500 pl-3">
     <div class="text-xl">Default Value:</div>
-    <div class="pl-5">{{ macros::render_single_type(type=page.extra.default_value) }}{% if page.extra.default_value_text %} | {{ page.extra.default_value_text }}{% endif %}</div>
+    <div class="pl-5">{{ macros::render_single_type(type=page.extra.default_value) }}{% if page.extra.default_value_desc %} | {{ page.extra.default_value_desc }}{% endif %}</div>
     </div>
     {% endif %}