From beaa532041620bd6eaf13e64a5f429d0214e473b Mon Sep 17 00:00:00 2001 From: ellemenno Date: Tue, 30 Jul 2019 22:45:23 -0400 Subject: [PATCH] improve operator descriptions and reference listing --- docs/_layouts/reference-list.html | 2 +- docs/_reference/Operators/op_address.md | 30 ++++++++++++++++++++- docs/_reference/Operators/op_assign.md | 2 ++ docs/_reference/Operators/op_const.md | 9 +++++++ docs/_reference/Operators/op_note.md | 2 ++ docs/_reference/Operators/op_ownership.md | 2 ++ docs/_reference/Operators/op_pointer.md | 16 +++++++---- docs/_reference/Operators/op_return-type.md | 9 +++++++ docs/_reference/Operators/op_string.md | 2 ++ docs/_reference/Operators/op_variable.md | 2 ++ docs/_reference/Types/any.md | 4 ++- 11 files changed, 72 insertions(+), 8 deletions(-) create mode 100644 docs/_reference/Operators/op_return-type.md diff --git a/docs/_layouts/reference-list.html b/docs/_layouts/reference-list.html index 14d8106..faf32ee 100644 --- a/docs/_layouts/reference-list.html +++ b/docs/_layouts/reference-list.html @@ -17,7 +17,7 @@

{{ page.title }}

{% if listable %}
-
{{ doc.title }}
+
{{ doc.title }}
{{ doc.description | newline_to_br | split: '
' | first | rstrip | markdownify | remove: '

' | remove: '

' }}
 diff --git a/docs/_reference/Operators/op_address.md b/docs/_reference/Operators/op_address.md index b4006be..ffb10c1 100644 --- a/docs/_reference/Operators/op_address.md +++ b/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
+> Jai does not use `&` for references; `using` can provide that functionality [^no-references] + +```cpp +{% include code/pointers.jai %} +``` + + +{% include footnotes.liquid references=page.footnotes %} diff --git a/docs/_reference/Operators/op_assign.md b/docs/_reference/Operators/op_assign.md index eca467a..b51246a 100644 --- a/docs/_reference/Operators/op_assign.md +++ b/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 }}` diff --git a/docs/_reference/Operators/op_const.md b/docs/_reference/Operators/op_const.md index c5eb598..bfed3af 100644 --- a/docs/_reference/Operators/op_const.md +++ b/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 diff --git a/docs/_reference/Operators/op_note.md b/docs/_reference/Operators/op_note.md index 46f7fab..8febaf0 100644 --- a/docs/_reference/Operators/op_note.md +++ b/docs/_reference/Operators/op_note.md @@ -2,6 +2,8 @@ layout: page title: '@' category: operator +description: annotate a declaration +search_tags: note at footnotes: - diff --git a/docs/_reference/Operators/op_ownership.md b/docs/_reference/Operators/op_ownership.md index 5f3b059..8201545 100644 --- a/docs/_reference/Operators/op_ownership.md +++ b/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 }}` diff --git a/docs/_reference/Operators/op_pointer.md b/docs/_reference/Operators/op_pointer.md index dfa9c3d..7a9ac45 100644 --- a/docs/_reference/Operators/op_pointer.md +++ b/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
+> Use `^` for address, `*` for value[^pointer-declaration] [^toward-away], `!` for ownership
> 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; ``` diff --git a/docs/_reference/Operators/op_return-type.md b/docs/_reference/Operators/op_return-type.md new file mode 100644 index 0000000..307ee54 --- /dev/null +++ b/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 }}` diff --git a/docs/_reference/Operators/op_string.md b/docs/_reference/Operators/op_string.md index e79191a..a0249d0 100644 --- a/docs/_reference/Operators/op_string.md +++ b/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 }}` diff --git a/docs/_reference/Operators/op_variable.md b/docs/_reference/Operators/op_variable.md index 3cb676d..41f954b 100644 --- a/docs/_reference/Operators/op_variable.md +++ b/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: - diff --git a/docs/_reference/Types/any.md b/docs/_reference/Types/any.md index dc7de5e..77f8cf7 100644 --- a/docs/_reference/Types/any.md +++ b/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: -