Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: annotations @Category and @Tags #1061

Merged
merged 9 commits into from
Apr 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/api/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand Down
9 changes: 9 additions & 0 deletions docs/api/safeds/lang/AnnotationTarget.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
Expand Down
22 changes: 22 additions & 0 deletions docs/api/safeds/lang/Category.md
Original file line number Diff line number Diff line change
@@ -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)
```
63 changes: 63 additions & 0 deletions docs/api/safeds/lang/DataScienceCategory.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 2 additions & 1 deletion docs/api/safeds/lang/Deprecated.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
3 changes: 2 additions & 1 deletion docs/api/safeds/lang/Experimental.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
2 changes: 1 addition & 1 deletion docs/api/safeds/lang/PythonCall.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 3 additions & 2 deletions docs/api/safeds/lang/PythonModule.md
Original file line number Diff line number Diff line change
@@ -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:**

Expand All @@ -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
)
Expand Down
2 changes: 1 addition & 1 deletion docs/api/safeds/lang/PythonName.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Expand Down
2 changes: 1 addition & 1 deletion docs/api/safeds/lang/Repeatable.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
25 changes: 25 additions & 0 deletions docs/api/safeds/lang/Tags.md
Original file line number Diff line number Diff line change
@@ -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>)
```
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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>
)
```
4 changes: 2 additions & 2 deletions docs/stub-language/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]:

Expand Down Expand Up @@ -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
Expand Down
Loading