update docs

cqllint/pkg/analyzer/testdata/src/repeated/set.go

@@ -74,3 +74,12 @@ func testSetDynamicSameValue() {
 		conditions.Product.Int.Set().Dynamic(conditions.Product.Int.Value()), // want "conditions.Product.Int is set to itself"
 	)
 }
+
+func testSetDynamicSameValueWithFunction() {
+	cql.Update[models.Product](
+		db,
+		conditions.Product.Int.Is().Eq(0),
+	).Set(
+		conditions.Product.Int.Set().Dynamic(conditions.Product.Int.Value().Plus(1)),
+	)
+}

docs/cql/cqllint.rst

@@ -12,7 +12,8 @@ It also adds other detections that would not generate runtime errors but are pos
 
 .. note::
 
-    At the moment, only the errors cql.ErrFieldModelNotConcerned and cql.ErrFieldIsRepeated are detected.
+    At the moment, only the errors cql.ErrFieldModelNotConcerned, cql.ErrFieldIsRepeated, 
+    cql.ErrAppearanceMustBeSelected and cql.ErrAppearanceOutOfRange are detected.
 
 We recommend integrating cqllint into your CI so that the use of cql ensures 100% that your queries will be executed correctly.
 
@@ -79,8 +80,6 @@ Now, if we run cqllint we will see the following report:
     $ cqllint ./...
     example.go:3: models.City is not joined by the query
 
-In this way, we will be able to correct this error without having to execute the query.
-
 ErrFieldIsRepeated
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -114,7 +113,71 @@ Now, if we run cqllint we will see the following report:
     example.go:5: conditions.Brand.Name is repeated
     example.go:6: conditions.Brand.Name is repeated
 
-In this way, we will be able to correct this error without having to execute the query.
+ErrAppearanceMustBeSelected
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To generate this error we must join the same model more than once and not select the appearance number:
+
+.. code-block:: go
+    :caption: example.go
+    :class: with-errors
+    :emphasize-lines: 9
+    :linenos:
+
+    _, err := cql.Query[models.Child](
+        db,
+        conditions.Child.Parent1(
+            conditions.Parent1.ParentParent(),
+        ),
+        conditions.Child.Parent2(
+            conditions.Parent2.ParentParent(),
+        ),
+        conditions.Child.ID.IsDynamic().Eq(conditions.ParentParent.ID.Value()),
+    ).Find()
+
+If we execute this query we will obtain an error of type `cql.ErrAppearanceMustBeSelected` with the following message:
+
+.. code-block:: none
+
+    field's model appears more than once, select which one you want to use with Appearance; model: models.ParentParent; operator: Eq; model: models.Child, field: ID
+
+Now, if we run cqllint we will see the following report:
+
+.. code-block:: none
+
+    $ cqllint ./...
+    example.go:9: models.ParentParent appears more than once, select which one you want to use with Appearance
+
+ErrAppearanceOutOfRange
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To generate this error we must use the Appearance method with a value greater than the number of appearances of a model:
+
+.. code-block:: go
+    :caption: example.go
+    :class: with-errors
+    :emphasize-lines: 4
+    :linenos:
+
+    _, err := cql.Query[models.Phone](
+        db,
+        conditions.Phone.Brand(
+            conditions.Brand.Name.IsDynamic().Eq(conditions.Phone.Name.Appearance(1).Value()),
+        ),
+    ).Find()
+
+If we execute this query we will obtain an error of type `cql.ErrAppearanceOutOfRange` with the following message:
+
+.. code-block:: none
+
+    selected appearance is bigger than field's model number of appearances; model: models.Phone; operator: Eq; model: models.Brand, field: Name
+
+Now, if we run cqllint we will see the following report:
+
+.. code-block:: none
+
+    $ cqllint ./...
+    example.go:4: selected appearance is bigger than models.Phone's number of appearances
 
 Misuses
 -------------------------
@@ -144,4 +207,30 @@ If we run cqllint we will see the following report:
 .. code-block:: none
 
     $ cqllint ./...
-    example.go:5: conditions.Brand.Name is set to itself
+    example.go:5: conditions.Brand.Name is set to itself
+
+Unnecessary Appearance selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the case when the Appearance method is used without being necessary, 
+i.e. when the model appears only once:
+
+.. code-block:: go
+    :caption: example.go
+    :class: with-errors
+    :emphasize-lines: 4
+    :linenos:
+
+    _, err := cql.Query[models.Phone](
+        db,
+        conditions.Phone.Brand(
+            conditions.Brand.Name.IsDynamic().Eq(conditions.Phone.Name.Appearance(0).Value()),
+        ),
+    ).Find()
+
+If we run cqllint we will see the following report:
+
+.. code-block:: none
+
+    $ cqllint ./...
+    example.go:4: Appearance call not necessary, models.Phone appears only once

docs/cql/type_safety.rst

@@ -189,8 +189,10 @@ there are still some possible cases that generate the following run-time errors:
 
 - cql.ErrFieldModelNotConcerned **(1)**: generated when trying to use a model that is not related 
   to the rest of the query (not joined).
-- cql.ErrAppearanceMustBeSelected: generated when you try to use a model that appears 
+- cql.ErrAppearanceMustBeSelected **(1)**: generated when you try to use a model that appears 
   (is joined) more than once in the query without selecting which one you want to use (see :ref:`cql/advanced_query:appearance`).
+- cql.ErrAppearanceOutOfRange **(1)**: generated when you try select an appearance number (with the Appearance method) 
+  greater than the number of appearances of a model. (see :ref:`cql/advanced_query:appearance`).
 - cql.ErrFieldIsRepeated **(1)**: generated when a field is repeated inside a Set call (see :doc:`/cql/update`).
 - cql.ErrOnlyPreloadsAllowed: generated when trying to use conditions within a preload of collections (see :ref:`cql/advanced_query:collections`).
 - cql.ErrUnsupportedByDatabase: generated when an attempt is made to use a method or function that is not supported by the database engine used.