docs: 18 language design

docs/language/common/aggregations.md

@@ -0,0 +1,23 @@
+# Aggregations
+
+To _aggregate_ [data][data] [grouped by][grouped by] an [ID][id] over a [function][functions] we can use the aggregation expression:
+
+```ttsl
+aggregate sum of salery, taxes groupedBy hh_id
+```
+
+Let's break down the syntax:
+
+- The keyword `#!ttsl aggregate`.
+- The [function][functions] to be executed on the grouped values (here `#!ttsl sum`).
+- The keyword `#!ttsl of`.
+- A [List][List] of [data][data] separated by a comma (here `#!ttsl salery, taxes`).
+- The [grouped by][grouped by] modifier (here with the id `#!ttsl hh_id`).
+
+An aggregation can be executed on one or multiple data values that are all connected to the same given [ID][id].
+
+[data]: data.md
+[grouped by]: modifier.md#grouped-by
+[id]: modifier.md#id
+[functions]: functions.md
+[List]: types.md#lists

docs/language/common/comments.md

@@ -4,33 +4,33 @@ Comments are mostly used to add explanations to the code for future readers —
 used to "comment out" code that you want to keep but that should not be run right now, since comments are ignored by the
 compiler.
 
-Safe-DS has three types of comments, namely
+TTSL has two types of comments, namely
 
-* [_line comments_](#line-comments), which end at a linebreak,
-* [_block comments_](#block-comments), which can cover multiple lines, and
-* [_documentation comments_](#documentation-comments), which are used to specify the documentation for declarations.
+* [_line comments_](#line-comments), which end at a linebreak, and
+* [_block comments_](#block-comments), which can cover multiple lines.
+* [_documentation comments_](#documentation-comments), which are used to document declarations.
 
 ## Line Comments
 
 Line comments stop at the end of a line:
 
-```sds
-// This is a comment.
+```ttsl
+# This is a comment.
 ```
 
-They start with `#!sds //`. There must be no space between the slashes. Everything after the double slashes in the same
+They start with `#!ttsl #`. Everything after the # in the same
 line is the text of the comment.
 
 To use line comments to "comment out" code you edit in VS Code, select the code and press ++ctrl+slash++ on your
-keyboard. This will add `#!sds //` to the beginning of each selected line. You can also trigger this functionality by
+keyboard. This will add `#!ttsl #` to the beginning of each selected line. You can also trigger this functionality by
 using the `Toggle Line Comment` command in the command palette. To remove the line comments, select the commented code
 and press ++ctrl+slash++ again.
 
 ## Block Comments
 
 Block comments have a start and end delimiter, which allows them to cover multiple lines:
 
-```sds
+```ttsl
 /*
 This
 is
@@ -39,11 +39,11 @@ comment
 */
 ```
 
-They start with `#!sds /*` and end at the inverted delimiter `#!sds */`. There must be no space between the slash
+They start with `#!ttsl /*` and end at the inverted delimiter `#!ttsl */`. There must be no space between the slash
 and the star. Block comments cannot be nested. Everything in between the delimiters is the text of the comment.
 
 To use block comments to "comment out" code you edit in VS Code, select the code and press ++ctrl+shift+slash++ on your
-keyboard. This will surround the selected code with `#!sds /*` and `#!sds */`. You can also trigger this functionality
+keyboard. This will surround the selected code with `#!ttsl /*` and `#!ttsl */`. You can also trigger this functionality
 by using the `Toggle Block Comment` command in the command palette. To remove the block comment, select the commented
 code and press ++ctrl+shift+slash++ again.
 
@@ -53,14 +53,14 @@ Documentation comments are special [block comments](#block-comments) that are us
 documentation is used in various places, e.g. when hovering over a declaration or one of its usage in VS Code. Here is
 an example:
 
-```sds
+```ttsl
 /**
  * This is a documentation comment.
  */
-class C
+function f() { ...
 ```
 
-They start with `#!sds /**` and end with `#!sds */`. There must be no spaces inside the delimiters. Documentation
+They start with `#!ttsl /**` and end with `#!ttsl */`. There must be no spaces inside the delimiters. Documentation
 comments cannot be nested. Everything in between the delimiters is the text of the comment, except an optional leading
 asterisk in each line, which is ignored. Documentation comments are attached to the declaration that follows them. If
 there is no declaration following the documentation comment, it is treated as a normal [block comment](#block-comments),
@@ -70,11 +70,11 @@ with no special meaning.
 
 Documentation comments support [Markdown](https://www.markdownguide.org/) to format the text. Here is an example:
 
-```sds
+```ttsl
 /**
  * This is a documentation comment with **bold** and *italic* text.
  */
-class C
+function f() { ...
 ```
 
 ### Tags
@@ -86,75 +86,55 @@ Documentation comments can contain tags to provide structured information.
 `{@link}` is an **inline** tag that can be used to link to another declaration. It takes the name of the declaration as
 an argument:
 
-```sds
+```ttsl
 /**
  * Computes the sum of two {@link Int}s.
  */
-fun sum(a: Int, b: Int): sum: Int
+function sum(x: Int, y: Int): Int { ...
 ```
 
 #### `@param`
 
-Use `@param` to document a [parameter][parameter] of a callable declaration. This tag takes the name of the parameter
+Use `@param` to document a parameter of a callable declaration. This tag takes the name of the parameter
 and its description as arguments. Since a callable can have multiple parameters, this tag can be used multiple times.
 
-```sds
+```ttsl
 /**
  * ...
  *
- * @param a The first integer.
- * @param b The second integer.
+ * @param x The first integer.
+ * @param y The second integer.
  */
-fun sum(a: Int, b: Int): sum: Int
+function sum(x: Int, y: Int): Int { ...
 ```
 
 #### `@result`
 
-Use `@result` to document a [result][result] of a callable declaration. This tag takes the name of the result and its
+Use `@result` to document a [result](functions.md) of a callable declaration. This tag takes the name of the result and its
 description as arguments. Since a callable can have multiple results, this tag can be used multiple times.
 
-```sds
+```ttsl
 /**
  * ...
  *
- * @result sum The sum of `a` and `b`.
+ * @result sum The sum of `x` and `y`.
  */
-fun sum(a: Int, b: Int): sum: Int
-```
-
-#### `@typeParam`
-
-Use `@typeParam` to document a [type parameter][type-parameter] of a generic declaration. This tag takes the name of the
-type parameter and its description as arguments. Since a generic declaration can have multiple type parameters, this
-tag can be used multiple times.
-
-```sds
-/**
- * ...
- *
- * @typeParam T The type of the elements in the list.
- */
-class List<T>
+function sum(x: Int, y: Int): Int { ...
 ```
 
 #### `@since`
 
 The `@since` tag can be used to specify when a declaration was added. It takes the version as argument and should be
 used only once.
 
-```sds
+```ttsl
 /**
  * ...
  *
  * @since 1.0.0
  */
-fun sum(a: Int, b: Int): sum: Int
+function sum(x: Int, y: Int): Int { ...
 ```
 
-[^1]: Except [parameter][parameter], [results][result], and [type parameters][type-parameter], which are documented with
-the [`@param`](#param), [`@result`](#result), and [`@typeParam`](#typeparam) tags on the containing declaration,
-respectively.
-
-[parameter]: parameters.md
-[result]: results.md
-[type-parameter]: ../stub-language/type-parameters.md
+[^1]: Except parameters and results, which are documented with the [`@param`](#param) and [`@result`](#result) tags on
+the containing declaration, respectively.

docs/language/common/constants.md

@@ -0,0 +1,33 @@
+# Constants
+
+_Constants_ define a constant value, that can only be defined once and can not be changed. A constant has a certain [type][types], [visibility][Visibility] and [validity][Validity].
+
+```ttsl
+constant value1: Int = 1
+
+
+Here are the pieces of syntax:
+
+- The keyword `#!ttsl constant`
+- The name of the constant (here `#!ttsl value1`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!ttsl lowerCamelCase` for the names of parameters.
+- A colon.
+- The [type][types] of the constant (here `#!ttsl Int`).
+- An equals sign.
+- The value of the constant (here `#!ttsl 1`). This must be a constant [expression][Expressions], i.e. something that can be evaluated by the compiler. Particularly [calls][calls] usually do not fulfill this requirement.
+
+## Visibility
+
+The [visibility][Visibility] of constants can be chosen by putting one of the three keywords `public`, `packageprivate`, `private` in front of the constant declaration. The default [visibility][Visibility] is public. Here is an example:
+
+```ttsl
+packageprivate constant value1: Int = 1
+```
+
+## Validity
+
+The documentation for the [validity of constants][constantValidity] can be found in the [validity][Validity] section.
+
+[types]: types.md
+[Visibility]: modifier.md#visibility
+[Validity]: validity.md
+[constantValidity]: validity.md#constants

docs/language/common/data.md

@@ -0,0 +1,35 @@
+# Data
+
+_Data_ defines a value given by the user via an input. It can then be accessed via a chosen namespace. Data has a certain [type][types], [visibility][Visibility], [validity][Validity] and can be an [id][id].
+
+```ttsl
+data PersonAge: Int;
+```
+
+Here are the pieces of syntax:
+
+- The keyword `#!ttsl data`
+- The name of the data (here `#!ttsl PersonAge`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!ttsl lowerCamelCase` for the names of parameters.
+- A colon.
+- The [type][types] of the data (here `#!ttsl Int`). Data can only be and Int, Float, Boolean or String.
+
+## Visibility
+
+The [visibility][Visibility] of data can be chosen by putting one of the three keywords `public`, `packageprivate`, `private` in front of the constant declaration. The default [visibility][Visibility] is public. Here is an example:
+
+```ttsl
+packageprivate data PersonAge: Int;
+```
+
+## ID
+
+There can also be an [ID modifier][id] added to the data to implicate that the data is unique and can be used to identify an object. The [ID modifier][id] is added by placing the keyword `id` in front of the data declaration. For example:
+
+```ttsl
+id data PersonID: Int;
+```
+
+[types]: types.md
+[id]: modifier.md#id
+[Visibility]: modifier.md#visibility
+[Validity]: validity.md