From 38aab8194b55062d832b1a11ae1ba8bd331eb869 Mon Sep 17 00:00:00 2001
From: Lukas Neubert <40118727+serkonda7@users.noreply.github.com>
Date: Thu, 30 Jan 2025 00:04:31 +0100
Subject: [PATCH] docs: unify section structure (#311)

---
 docs/design/syntax.md | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/docs/design/syntax.md b/docs/design/syntax.md
index a906b815..1750ddf5 100644
--- a/docs/design/syntax.md
+++ b/docs/design/syntax.md
@@ -3,14 +3,22 @@ Why is the syntax the way it is?
 
 
 ## No Block Comments
-Bait does not support block comments:
-- Complicates lexing and parsing, especially nested block comments
-- Hard to format, especially inline comments _(a built-in formatter is planned)_
+Bait only supports line comments (`//`) and _no_ block comments (`/* */`).
 
-Using a decent editor with line wrapping and shortcuts,
-you can achieve almost the same level of convenience!
+### Benefits
+- **Simpler lexing parsing**: Nested block comments are somewhat complicated
+- **Improved Readability**: Line comments are unlikely to disrupt the visual flow of code
+- **Code is easily formattable**
+
+### Drawbacks
+- Hard to comment larger passages
+- Potentially long comment lines
 
-For details, I recommend reading https://futhark-lang.org/blog/2017-10-10-block-comments-are-a-bad-idea.html.
+### Mitigation
+Modern editors and IDEs support line wrapping and shortcuts for (un)commenting.
+
+### References
+- https://futhark-lang.org/blog/2017-10-10-block-comments-are-a-bad-idea.html.
 
 
 ## Casting: `val as Type`
@@ -31,7 +39,7 @@ For details, I recommend reading https://futhark-lang.org/blog/2017-10-10-block-
 
 ### References
 - [Discord: Thoughts by @zeozeozeo](https://discord.com/channels/1204569231992295494/1204741190432325652/1302526862982905866)
-- [soc.me: `ident: Type` over `Type ident`](https://soc.me/languages/type-annotations)
+- https://soc.me/languages/type-annotations
 
 
 ## Static Variables