feat: annotations @Category and @Tags (#1061)

Closes #1021 ### Summary of Changes * New annotation `@Category` to assign a data science category (data import, data preparation, ...) to a declaration. This can be used to group declarations in the toolbox of the upcoming graphical view/editor. The documentation generator could also use this information. * New annotation `@Tags` to assign tags to a declaration. This can be used for filtering in the upcoming graphical view/editor. Again, the documentation generator could also include this information somewhere.
Safe-DS · Apr 18, 2024 · e45a4c9 · e45a4c9
1 parent 09ca1cf
commit e45a4c9
Show file tree

Hide file tree

Showing 39 changed files with 587 additions and 63 deletions.
diff --git a/docs/api/SUMMARY.md b/docs/api/SUMMARY.md
@@ -32,6 +32,8 @@ search:
         - [AnnotationTarget](safeds/lang/AnnotationTarget.md)
         - [Any](safeds/lang/Any.md)
         - [Boolean](safeds/lang/Boolean.md)
+        - [Category](safeds/lang/Category.md)
+        - [DataScienceCategory](safeds/lang/DataScienceCategory.md)
         - [Deprecated](safeds/lang/Deprecated.md)
         - [Experimental](safeds/lang/Experimental.md)
         - [Expert](safeds/lang/Expert.md)
@@ -49,7 +51,8 @@ search:
         - [PythonName](safeds/lang/PythonName.md)
         - [Repeatable](safeds/lang/Repeatable.md)
         - [String](safeds/lang/String.md)
-        - [Target](safeds/lang/Target.md)
+        - [Tags](safeds/lang/Tags.md)
+        - [Targets](safeds/lang/Targets.md)
     - ml
         - classical
             - classification

diff --git a/docs/api/safeds/lang/AnnotationTarget.md b/docs/api/safeds/lang/AnnotationTarget.md
@@ -57,6 +57,11 @@ The declaration types that can be targeted by annotations.
          */
         Result
 
+        /**
+         * The annotation can be called on schemas.
+         */
+        Schema
+
         /**
          * The annotation can be called on segments.
          */
@@ -109,6 +114,10 @@ The annotation can be called on pipelines.
 
 The annotation can be called on results.
 
+## Schema {#safeds.lang.AnnotationTarget.Schema data-toc-label='Schema'}
+
+The annotation can be called on schemas.
+
 ## Segment {#safeds.lang.AnnotationTarget.Segment data-toc-label='Segment'}
 
 The annotation can be called on segments.

diff --git a/docs/api/safeds/lang/Category.md b/docs/api/safeds/lang/Category.md
@@ -0,0 +1,22 @@
+# :test_tube:{ title="Experimental" } `#!sds annotation` Category {#safeds.lang.Category data-toc-label='Category'}
+
+The category of a declaration. It can be used for grouping.
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `category` | [`DataScienceCategory`][safeds.lang.DataScienceCategory] | - | - |
+
+**Targets:**
+
+- `Class`
+- `Enum`
+- `Function`
+- `Segment`
+
+??? quote "Stub code in `ideIntegration.sdsstub`"
+
+    ```sds linenums="20"
+    annotation Category(category: DataScienceCategory)
+    ```
diff --git a/docs/api/safeds/lang/DataScienceCategory.md b/docs/api/safeds/lang/DataScienceCategory.md
@@ -0,0 +1,63 @@
+# `#!sds enum` DataScienceCategory {#safeds.lang.DataScienceCategory data-toc-label='DataScienceCategory'}
+
+A step in the data science process.
+
+??? quote "Stub code in `ideIntegration.sdsstub`"
+
+    ```sds linenums="25"
+    enum DataScienceCategory {
+        /**
+         * Load your data into the program.
+         */
+        DataImport
+
+        /**
+         * Prepare your data for analysis.
+         */
+        DataPreparation
+
+        /**
+         * Explore your data.
+         */
+        DataExploration
+
+        /**
+         * Save your data for later use.
+         */
+        DataExport
+
+        /**
+         * Configure a model and train it on your data.
+         */
+        Modeling
+
+        /**
+         * Evaluate the performance of your model.
+         */
+        ModelEvaluation
+    }
+    ```
+
+## DataExploration {#safeds.lang.DataScienceCategory.DataExploration data-toc-label='DataExploration'}
+
+Explore your data.
+
+## DataExport {#safeds.lang.DataScienceCategory.DataExport data-toc-label='DataExport'}
+
+Save your data for later use.
+
+## DataImport {#safeds.lang.DataScienceCategory.DataImport data-toc-label='DataImport'}
+
+Load your data into the program.
+
+## DataPreparation {#safeds.lang.DataScienceCategory.DataPreparation data-toc-label='DataPreparation'}
+
+Prepare your data for analysis.
+
+## ModelEvaluation {#safeds.lang.DataScienceCategory.ModelEvaluation data-toc-label='ModelEvaluation'}
+
+Evaluate the performance of your model.
+
+## Modeling {#safeds.lang.DataScienceCategory.Modeling data-toc-label='Modeling'}
+
+Configure a model and train it on your data.
diff --git a/docs/api/safeds/lang/Deprecated.md b/docs/api/safeds/lang/Deprecated.md
@@ -21,11 +21,12 @@ The declaration should no longer be used.
 - `Function`
 - `Parameter`
 - `Result`
+- `Schema`
 - `Segment`
 
 ??? quote "Stub code in `maturity.sdsstub`"
 
-    ```sds linenums="22"
+    ```sds linenums="23"
     annotation Deprecated(
         alternative: String? = null,
         reason: String? = null,

diff --git a/docs/api/safeds/lang/Experimental.md b/docs/api/safeds/lang/Experimental.md
@@ -12,10 +12,11 @@ The declaration might change without a major version bump.
 - `Function`
 - `Parameter`
 - `Result`
+- `Schema`
 - `Segment`
 
 ??? quote "Stub code in `maturity.sdsstub`"
 
-    ```sds linenums="43"
+    ```sds linenums="45"
     annotation Experimental
     ```
diff --git a/docs/api/safeds/lang/PythonCall.md b/docs/api/safeds/lang/PythonCall.md
@@ -1,7 +1,7 @@
 # :test_tube:{ title="Experimental" } `#!sds annotation` PythonCall {#safeds.lang.PythonCall data-toc-label='PythonCall'}
 
 The specification of a corresponding function call in Python. By default, the function is called as specified in the
-stub.
+stubs.
 
 The specification can contain template expressions, which are replaced by the corresponding arguments of the function
 call. `$this` is replaced by the receiver of the call. `$param` is replaced by the value of the parameter called

diff --git a/docs/api/safeds/lang/PythonModule.md b/docs/api/safeds/lang/PythonModule.md
@@ -1,6 +1,7 @@
 # `#!sds annotation` PythonModule {#safeds.lang.PythonModule data-toc-label='PythonModule'}
 
-The qualified name of the corresponding Python module. By default, this is the qualified name of the package.
+The qualified name of the corresponding Python module. By default, this is the qualified name of the package in the
+stubs.
 
 **Parameters:**
 
@@ -14,7 +15,7 @@ The qualified name of the corresponding Python module. By default, this is the q
 
 ??? quote "Stub code in `codeGeneration.sdsstub`"
 
-    ```sds linenums="21"
+    ```sds linenums="22"
     annotation PythonModule(
         qualifiedName: String
     )

diff --git a/docs/api/safeds/lang/PythonName.md b/docs/api/safeds/lang/PythonName.md
@@ -21,7 +21,7 @@ The name of the corresponding API element in Python. By default, this is the nam
 
 ??? quote "Stub code in `codeGeneration.sdsstub`"
 
-    ```sds linenums="38"
+    ```sds linenums="39"
     annotation PythonName(
         name: String
     )

diff --git a/docs/api/safeds/lang/Repeatable.md b/docs/api/safeds/lang/Repeatable.md
@@ -8,6 +8,6 @@ The annotation can be called multiple times for the same declaration.
 
 ??? quote "Stub code in `annotationUsage.sdsstub`"
 
-    ```sds linenums="83"
+    ```sds linenums="88"
     annotation Repeatable
     ```
diff --git a/docs/api/safeds/lang/Tags.md b/docs/api/safeds/lang/Tags.md
@@ -0,0 +1,25 @@
+# :test_tube:{ title="Experimental" } `#!sds annotation` Tags {#safeds.lang.Tags data-toc-label='Tags'}
+
+Tags to associate with a declaration. They can be used for filtering.
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `tags` | [`List<String>`][safeds.lang.List] | - | - |
+
+**Targets:**
+
+- `Annotation`
+- `Class`
+- `Enum`
+- `Function`
+- `Pipeline`
+- `Schema`
+- `Segment`
+
+??? quote "Stub code in `ideIntegration.sdsstub`"
+
+    ```sds linenums="70"
+    annotation Tags(tags: List<String>)
+    ```
diff --git a/docs/api/safeds/lang/Target.md → docs/api/safeds/lang/Targets.md b/docs/api/safeds/lang/Target.md → docs/api/safeds/lang/Targets.md
@@ -1,4 +1,4 @@
-# `#!sds annotation` Target {#safeds.lang.Target data-toc-label='Target'}
+# `#!sds annotation` Targets {#safeds.lang.Targets data-toc-label='Targets'}
 
 The annotation must target only the specified declaration types. By default, any declaration type can be targeted.
 
@@ -15,7 +15,7 @@ The annotation must target only the specified declaration types. By default, any
 ??? quote "Stub code in `annotationUsage.sdsstub`"
 
     ```sds linenums="9"
-    annotation Target(
+    annotation Targets(
         targets: List<AnnotationTarget>
     )
     ```
diff --git a/docs/stub-language/annotations.md b/docs/stub-language/annotations.md
@@ -53,7 +53,7 @@ To attach metainformation to a declaration, the annotation must be called on tha
 - [Type parameters][type-parameters]
 - [Pipelines][pipelines]
 
-The valid targets of an annotation can be restricted with the [`Target`][safeds.lang.Target] annotation. By default all targets are allowed. Likewise, an annotation can only be called once on the same declaration by default, unless the annotation is marked as[Repeatable][safeds.lang.Repeatable].
+The valid targets of an annotation can be restricted with the [`Targets`][safeds.lang.Targets] annotation. By default all targets are allowed. Likewise, an annotation can only be called once on the same declaration by default, unless the annotation is marked as[Repeatable][safeds.lang.Repeatable].
 
 Annotation calls are always located right in front of their target. Exception: In the case of compilations units they are located at the very top of the file. Here is an example that demonstrates how to call the annotation `#!sds OnlyForExperts` that we defined above on a [class][classes]:
 
@@ -89,7 +89,7 @@ The same [restrictions to arguments][argument-restrictions] as for [calls][calls
 
 The package `#!sds safeds.lang` contains several annotations that are processed by Safe-DS. Particularly important are the annotations
 
-- [`Target`][safeds.lang.Target], which can restrict the possible targets of an annotation, and
+- [`Targets`][safeds.lang.Targets], which can restrict the possible targets of an annotation, and
 - [`Repeatable`][safeds.lang.Repeatable], which allows an annotation to be called multiple times on the same declaration.
 
 [parameters]: parameters.md