docs: use titles for code blocks (#697)

### Summary of Changes

Use titles for code blocks to differentiate whether they denote Python
code or Safe-DS code. Remove the old comments inside the code blocks
that expressed the same thing.

docs/language/common/imports.md

@@ -1,6 +1,6 @@
 # Imports
 
-By default, only declarations in the same package as the current file or in the `safeds.lang` [package][packages] are accessible. All other declarations must be imported first.
+By default, only declarations in the same package as the current file or in a package whose name starts with `safeds` [package][packages] are accessible. All other declarations must be imported first.
 
 Safe-DS has two kinds of imports, namely a _qualified import_, which imports a single declaration, and a _wildcard import_, which imports everything in a [package][packages].
 

docs/language/common/packages.md

@@ -25,29 +25,23 @@ In order for code generation to work properly, the Safe-DS package of a Safe-DS
 
 The first option is to use the file that contains the actual implementation of the declaration. Let us start with the following Python code to explain this idea:
 
-```py
-# Python file "safeds/model/regression/_decision_tree.py"
-
+```py title="Python file 'safeds/model/regression/_decision_tree.py'"
 class DecisionTree:
     def __init__(self):
         pass # Implementation omitted
 ```
 
 This file contains the actual implementation of the Python class `#!py DecisionTree`. We now want to make this Python class available in Safe-DS, which requires the following Safe-DS stub file:
 
-```sds
-// Safe-DS file "safeds/model/regression/_decision_tree/DecisionTree.sdsstub"
-
+```sds title="Safe-DS file 'safeds/model/regression/_decision_tree/DecisionTree.sdsstub'"
 package safeds.model.regression._decision_tree
 
 class DecisionTree()
 ```
 
 Note that the Safe-DS package corresponds to the path to the Python file, where we replace file separators (here `/`) by dots and remove the file extension (here `.py`). Another way to think about this is to ask how a from-import of the Python declaration would look like in Python code that wants to use the Python declaration. In this case we would write
 
-```py
-# Python
-
+```py title="Python"
 from safeds.model.regression._decision_tree import DecisionTree
 ```
 
@@ -61,33 +55,25 @@ The second option is to chose the Safe-DS package that corresponds to a [Python
 
 We will demonstrate this by extending the example we used above:
 
-```py
-# Python file "safeds/model/regression/_decision_tree.py"
-
+```py title="Python file 'safeds/model/regression/_decision_tree.py'"
 class DecisionTree:
     def __init__(self):
         pass # Implementation omitted
 ```
 
-```py
-# Python file "safeds/model/regression/__init__.py
-
+```py title="Python file 'safeds/model/regression/__init__.py'"
 from ._decision_tree import DecisionTree
 ```
 
 The addition of the `__init__.py` file now allows us to import the Python class `#!py DecisionTree` in another way in Python client code:
 
-```py
-# Python
-
+```py title="Python"
 from safeds.model.regression import DecisionTree
 ```
 
 Note the omission of the suffix `#!py ._decision_tree` after `#!py safeds.model.regression`. Likewise, we can now update the Safe-DS stub code. We again just take everything between `#!py from` and `#!py import` and use this as the Safe-DS package name:
 
-```sds
-// Safe-DS file "safeds/model/regression/DecisionTree.sdsstub"
-
+```sds title="Safe-DS file 'safeds/model/regression/DecisionTree.sdsstub'"
 package safeds.model.regression
 
 class DecisionTree()
@@ -105,29 +91,23 @@ Choosing the Safe-DS package according to the rules described above is essential
 
 The first two options are self-explanatory. Let us now look at the third one. We use our initial example from the Section ["File Contains Implementation"](#file-contains-implementation) again:
 
-```py
-# Python file "safeds/model/regression/_decision_tree.py"
-
+```py title="Python file 'safeds/model/regression/_decision_tree.py'"
 class DecisionTree:
     def __init__(self):
         pass # Implementation omitted
 ```
 
 Our original solution leads to a warning because the Safe-DS package name contains the segment `#!sds _decision_tree`, which is not `#!sds lowerCamelCase` due to the underscores:
 
-```sds
-// Safe-DS file "safeds/model/regression/_decision_tree/DecisionTree.sdsstub"
-
+```sds title="Safe-DS file 'safeds/model/regression/_decision_tree/DecisionTree.sdsstub'"
 package safeds.model.regression._decision_tree
 
 class DecisionTree()
 ```
 
 By [calling][annotation-calls] the [annotation][annotations] `#!sds @PythonModule`, we can also specify the corresponding [Python module][python-modules], however. If this [annotation][annotations] is [called][annotation-calls], it takes precedence over the Safe-DS package name. This allows us to pick an arbitrary Safe-DS package that respects the Safe-DS naming convention. We can even group multiple [Python modules][python-modules] together in one Safe-DS package without relying on Python's `#!sds __init__.py` files:
 
-```sds
-// Safe-DS file "safeds/model/regression/DecisionTree.sdsstub"
-
+```sds title="Safe-DS file 'safeds/model/regression/DecisionTree.sdsstub'" hl_lines="1"
 @PythonModule("safeds.model.regression._decision_tree")
 
 package safeds.model.regression
@@ -140,11 +120,9 @@ Here is a breakdown of this:
 - We [call][annotation-calls] the `#!sds @PythonModule` [annotation][annotations] before we declare the Safe-DS package. The [Python module][python-modules] that exports the Python declarations that correspond to the Safe-DS declarations in this stub file is passed as a [string literal][string-literals] (here `#!sds safeds.model.regression._decision_tree`). This is used only for code generation and does not affect users of Safe-DS.
 - We specify the Safe-DS package as usual. This must be used when we [import][imports] the declaration in another Safe-DS file:
 
-    `#!sds ``sds
-    // Safe-DS
-
-    from safeds.model.regression import DecisionTree
-    `#!sds ``
+```sds title="Safe-DS"
+from safeds.model.regression import DecisionTree
+```
 
 It is important to note that the `#!sds @PythonModule` annotation only affects the one Safe-DS file that contains it rather than the entire Safe-DS package. This allows different Safe-DS files in the same package to point to different [Python modules][python-modules].
 

docs/language/common/parameters.md

@@ -74,16 +74,12 @@ Let's look at these elements in turn.
 
 By default, parameter names in Safe-DS must be identical to their names in Python. If this is not desired, for example due to clashing name conventions in Safe-DS and Python, the `#!sds @PythonName` annotation can be used to link a Safe-DS parameter to a Python parameter with a different name. Here is an example:
 
-```py
-# Python code
-
+```py title="Python"
 def accuracy(x_pred: Dataset, x_test: Dataset) -> float:
     pass
 ```
 
-```sds
-// Safe-DS code
-
+```sds title="Safe-DS" hl_lines="2-3"
 fun accuracy(
     @PythonName("x_pred") xPred: Dataset,
     @PythonName("x_test") xTest: Dataset
@@ -114,31 +110,23 @@ The following three examples show valid pairs of Python and Safe-DS programs.
 
 #### Required Parameter
 
-```py
-# Python code
-
+```py title="Python"
 def required(a: int):
     pass
 ```
 
-```sds
-// Safe-DS code
-
+```sds title="Safe-DS"
 fun required(a: Int)
 ```
 
 #### Optional Parameter
 
-```py
-# Python code
-
+```py title="Python"
 def optional(a: int = 1):
     pass
 ```
 
-```sds
-// Safe-DS code
-
+```sds title="Safe-DS"
 fun optional(a: Int = 1)
 ```
 

docs/language/pipeline-language/segments.md

@@ -97,7 +97,7 @@ segment loadMovieRatingsSample(nInstances: Int) -> (features: Dataset, target: D
 
 In the assignment beginning with `#!sds yield features =` we specify the value of the result called `#!sds features`, while the next assignment beginning with `#!sds yield target =` assigns a value to the `#!sds target` result.
 
-The order of the [result declarations](#result-declaration) does not need to match the order of assignment. However, **each result musts be assigned exactly once**. Note that unlike the `#!sds return` in other programming languages, `#!sds yield` does not stop the execution of the segment, which allows [assignments][assignments] to different results to be split across multiple [statements][statements].
+The order of the [result declarations](#result-declaration) does not need to match the order of assignment. However, **each result must be assigned exactly once**. Note that unlike the `#!sds return` in other programming languages, `#!sds yield` does not stop the execution of the segment, which allows [assignments][assignments] to different results to be split across multiple [statements][statements].
 
 ## Visibility
 

docs/language/stub-language/annotations.md

@@ -57,7 +57,7 @@ The valid targets of an annotation can be restricted with the [`Target`][safeds-
 
 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]:
 
-```sds
+```sds hl_lines="1"
 @OnlyForExperts
 class VerySpecificMLModel
 ```
@@ -71,14 +71,14 @@ The code `#!sds class VerySpecificMLModel` is **not** part of the annotation cal
 
 For an annotation with parameters, such as the `#!sds Category` annotation that we defined above, we must pass arguments. The same syntax is used for arguments of annotation calls as for normal [calls][calls]. We can use positional arguments:
 
-```sds
+```sds hl_lines="1"
 @Category("model")
 class VerySpecificMLModel
 ```
 
 Or we can use named arguments:
 
-```sds
+```sds hl_lines="1"
 @Category(category="model")
 class VerySpecificMLModel
 ```