docs/reference: update comments, literals sections

1 files changed, 19 insertions, 4 deletions

diff --git a/docs/reference/01_syntax.md b/docs/reference/01_syntax.md
index 4db70f9..30827f3 100644
--- a/docs/reference/01_syntax.md
+++ b/docs/reference/01_syntax.md
@@ -2,7 +2,7 @@
 whitespace. Each expression may be either a literal constant or a cell.
 
 # literal constants
-There are three types of literals with different syntax:
+There are three types of simple literals with different syntax:
 
 ## numbers
 Numbers consist of the digits `0`-`9` and can optionally begin with a
@@ -78,7 +78,7 @@ behaviour of the cell.
 Tags consist of one or more digits (`0`-`9`) enclosed in square brackets (`[`
 and `]`). `[1]` and `[255]` are examples of valid tags.
 
-## template strings
+# template strings
 Template Strings are a different syntax for cells that allows embedding alv
 expressions inside of a string literal. They can be used to perform string
 substitution, especially within code of other languages.
@@ -106,6 +106,17 @@ semantically identical to the previous examples respectively:
     ([99]fmt ["five is" ""] (+ 3 2))
     (fmt ["there is $no substitution here"])
 
+# arrays and structs
+Array and struct literals too are syntatic shortcuts for the [mkarray][] and
+[mkstruct][] builtins respectively.
+
+Arrays are a list of expressions separated by whitespace enclosed in square
+brackets (`[` and `]`). Similarly structs are a list of key-value pairs
+separated by whitespace and enclosed in curly brackets (`{` and `}`).
+
+Arrays and structs must contain at least one element or key-value pair
+respectively.
+
 # whitespace
 The space, tab, newline, and line-feed special characters constitute whitespace
 and may be repeated any number of times to form a chunk. A chunk of whitespace
@@ -113,5 +124,9 @@ may also contain any number of comments, but may neither begin nor end with a
 comment.
 
 ## comments
-A comment begins with `#(` and ends with a matching parenthesis `)`. Comments
-may contain other comments or cells.
+A comment cell begins with `#(` and ends with a matching parenthesis `)`.
+Comment cells may contain other comments or cells.
+
+Line comments begin with `##` and end at the end of the line. Line comments
+have precedence over comment cells, i.e. comment cells within line comments do
+not continue past the end of the line.