Issue/6409 improve language reference documentation

changelogs/unreleased/6409-improve-language-reference-documentation.yml

@@ -0,0 +1,4 @@
+description: Add language reference documentation.
+issue-nr: 6409
+change-type: patch
+destination-branches: [master, iso6]

docs/language.rst

@@ -120,6 +120,21 @@ Literal values can be assigned to variables
     import ip::services
     sshservice = ip::services::ssh
 
+.. note::
+    It is possible to make a string span multiple lines by triple quoting it e.g.:
+
+.. code-block:: inmanta
+
+    multi_line_string = """This
+    string
+    spans
+    multiple
+    lines"""
+
+.. note::
+    Raw and format string (see :ref:`language_reference_string_formatting`) treat backslashes as regular characters.
+    On the other hand, in regular and multi-line strings, escape characters (e.g. ``\n``, ``\t``...) are interpreted and
+    therefore backslashes need to be escaped in order to be displayed.
 
 
 Primitive types
@@ -384,7 +399,7 @@ any values to the relation attribute.
     // adding a value twice does not affect the relation,
     // s1.files still equals [f1, f2, f3]
 
-In addition, attributes can be assigned in a constructor using keyword arguments by using `**dct` where `dct` is a dictionary that contains
+In addition, attributes can be assigned in a constructor using keyword arguments by using ``**dct`` where ``dct`` is a dictionary that contains
 attribute names as keys and the desired values as values. For example:
 
 .. code-block:: inmanta
@@ -395,6 +410,22 @@ attribute names as keys and the desired values as values. For example:
     file1_config = {"path": "/opt/1"}
     f1 = File(host=h1, **file1_config)
 
+It is also possible to append elements to a relation with the ``+=`` operator:
+
+.. code-block:: inmanta
+
+    Host.files [0:] -- File.host [1]
+
+    h1 = Host("test")
+    h1.files += f1
+    h1.files += f2
+    h1.files += f3
+
+    // h1.files equals [f1, f2, f3]
+
+
+.. note::
+    This syntax is only defined for relations. The ``+=`` operator can not be used on variables, which are immutable.
 
 Referring to instances
 ++++++++++++++++++++++
@@ -436,10 +467,11 @@ When nesting constructors, short names can be used for the nested constructors,
         )
     )
 
-However, when relying on type inference,
+However, when relying on type inference:
+
 1. avoid creating sibling types with the same name, but different fully qualified name, as they may become indistinguishable, breaking the inference on existing models.
 
-    1. if multiple types exist with the same name, and one is in scope, that one is selected (i.e it is defined in this module, a parent module or `std`)
+    1. if multiple types exist with the same name, and one is in scope, that one is selected (i.e. it is defined in this module, a parent module or ``std``)
     2. if multiple types exist that are all out of scope, inference fails
 
 2. make sure the type you want to infer is imported somewhere in the model. Otherwise the compiler will not find it.
@@ -680,6 +712,8 @@ To prevent string interpolation, use raw strings
     motd = r"Welcome to {{hostname}}\n"
 
 
+.. _language_reference_string_formatting:
+
 String formatting
 +++++++++++++++++
 

src/inmanta/protocol/methods_v2.py

@@ -1309,11 +1309,13 @@ def get_environment_metrics(
     :param end_interval: The end of the time window for which the metrics should be returned.
     :param nb_datapoints: The amount of datapoint that will be returned within the given time interval for each metric.
     :param round_timestamps: If this parameter is set to True, the timestamps in the reply will be rounded to a full hour.
-                             All time windows in the reply will have an equal size. To achieve this the start_interval,
-                             end_interval and nb_datapoint in the reply may differ from the ones requested.
-                               * The start_interval may be smaller than requested
-                               * The end_interval may be larger than requested
-                               * The nb_datapoints may be larger than requested
+        All time windows in the reply will have an equal size. To achieve this the start_interval, end_interval and
+        nb_datapoint in the reply may differ from the ones requested.
+
+            * The start_interval may be smaller than requested
+            * The end_interval may be larger than requested
+            * The nb_datapoints may be larger than requested
+
     :raises BadRequest: start_interval >= end_interval
     :raises BadRequest: nb_datapoints < 0
     :raises BadRequest: The provided metrics list is an empty list.