improve operator descriptions and reference listing

docs/_layouts/reference-list.html

@@ -17,7 +17,7 @@ <h1 id="heading" class="ui dividing header">{{ page.title }}</h1>
   {% if listable %}
   <a class="item" href="{{ site.baseurl }}{{ doc.url }}#/{{ doc.collection | downcase }}/">
     <div class="content">
-      <div class="medium header">{{ doc.title }}</div>
+      <div class="medium header"><tt>{{ doc.title }}</tt></div>
       <div class="description">{{ doc.description | newline_to_br | split: '<br />' | first | rstrip | markdownify | remove: '<p>' | remove: '</p>' }}</div>
     </div>
   </a>

docs/_reference/Operators/op_address.md

@@ -2,7 +2,35 @@
 layout: page
 title: '*'
 category: operator
-search_tags: pointer address
+description: get a value by dereferencing a memory address
+search_tags: dereference pointer memory star asterisk
+
+footnotes:
+ -
+    label: no-references
+    video: demo_20150121_qa
+    time:  840
+    text:  references in C++ are just pointers with a different syntax and different defaults, so I would rather have a way to have one thing.
+ -
+    label: pointer-declaration
+    video: demo_20141210
+    time:  769
+    text:  for pointers, use Pascal-style pointy hat (`^`) instead of ampersand (`&`). still use star (`*`) to dereference a pointer.
+ -
+    label: toward-away
+    video: demo_20141210
+    time:  821
+    text:  star (`*`) brings us toward the value, and hat (`^`) brings us away from the value.
 ---
 
 # `{{ page.title }}`
+
+> Use `*` for value, `^` for address[^pointer-declaration] [^toward-away], `!` for ownership <br>
+> Jai does not use `&` for references; `using` can provide that functionality [^no-references]
+
+```cpp
+{% include code/pointers.jai %}
+```
+
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_reference/Operators/op_assign.md

@@ -2,6 +2,8 @@
 layout: page
 title: '='
 category: operator
+description: assign a value
+search_tags: assign assignment equal
 ---
 
 # `{{ page.title }}`

docs/_reference/Operators/op_const.md

@@ -2,6 +2,15 @@
 layout: page
 title: '::'
 category: operator
+description: declare a constant (unchanging) value
+search_tags: const constant colon
 ---
 
 # `{{ page.title }}`
+
+Constants in Jai include:
+
+* static values
+* enums
+* structs
+* procedures

docs/_reference/Operators/op_note.md

@@ -2,6 +2,8 @@
 layout: page
 title: '@'
 category: operator
+description: annotate a declaration
+search_tags: note at
 
 footnotes:
  -

docs/_reference/Operators/op_ownership.md

@@ -2,6 +2,8 @@
 layout: page
 title: '!'
 category: operator
+description: indicate memory ownership
+search_tags: memory ownership bang exclamation
 ---
 
 # `{{ page.title }}`

docs/_reference/Operators/op_pointer.md

@@ -2,6 +2,8 @@
 layout: page
 title: '^'
 category: operator
+description: get a pointer to a value's memory address
+search_tags: memory pointer caret hat
 
 footnotes:
  -
@@ -14,19 +16,23 @@ footnotes:
     video: demo_20141210
     time:  769
     text:  for pointers, use Pascal-style pointy hat (`^`) instead of ampersand (`&`). still use star (`*`) to dereference a pointer.
+ -
+    label: toward-away
+    video: demo_20141210
+    time:  821
+    text:  star (`*`) brings us toward the value, and hat (`^`) brings us away from the value.
 ---
 
 # `{{ page.title }}`
 
-> Use `^` for pointer, `*` for address[^pointer-declaration], `!` for ownership <br>
+> Use `^` for address, `*` for value[^pointer-declaration] [^toward-away], `!` for ownership <br>
 > Jai does not use `&` for references; `using` can provide that functionality [^no-references]
 
 ```cpp
-e : Entity;
-
-pointer : ^Entity;
-pointer = *e;
+{% include code/pointers.jai %}
+```
 
+```cpp
 owned : node *! = null;
 other : node *  = *graph.node;
 ```

docs/_reference/Operators/op_return-type.md

@@ -0,0 +1,9 @@
+---
+layout: page
+title: '->'
+category: operator
+description: define return type(s) for a procedure
+search_tags: return type arrow
+---
+
+# `{{ page.title }}`

docs/_reference/Operators/op_string.md

@@ -2,6 +2,8 @@
 layout: page
 title: '"'
 category: operator
+description: enclose a string literal
+search_tags: string double quote
 ---
 
 # `{{ page.title }}`

docs/_reference/Operators/op_variable.md

@@ -2,6 +2,8 @@
 layout: page
 title: ':'
 category: operator
+description: declare a variable; can be paired with assignment
+search_tags: declaration assignment colon
 
 footnotes:
  -

docs/_reference/Types/any.md

@@ -2,7 +2,9 @@
 layout: page
 title: Any
 category: type
-description: a more informative and type-safe version of `void` pointer.\n\nIncludes a type pointer for the type and a void pointer for the value.
+description: |-
+  a more informative and type-safe version of `void` pointer.
+  Includes a type pointer for the type and a void pointer for the value.
 
 footnotes:
  -