docs: Add paragraph about @ operator (#5822)

Co-authored-by: Bjorn Neergaard <bjorn@neersighted.com>

docs/cli.md

@@ -304,6 +304,10 @@ poetry add "pendulum>=2.0.5"
 poetry add pendulum==2.0.5
 ```
 
+{{% note %}}
+See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about the `@` operator.
+{{% /note %}}
+
 If you try to add a package that is already present, you will get an error.
 However, if you specify a constraint, like above, the dependency will be updated
 by using the specified constraint.

docs/dependency-specification.md

@@ -84,6 +84,39 @@ You can specify the exact version of a package.
 This will tell Poetry to install this version and this version only.
 If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures.
 
+### Using the `@` operator
+
+When adding dependencies via `poetry add`, you can use the `@` operator.
+This is understood similarly to the `==` syntax, but also allows prefixing any
+specifiers that are valid in `pyproject.toml`. For example:
+
+```shell
+poetry add django@^4.0.0
+```
+
+The above would translate to the following entry in `pyproject.toml`:
+```toml
+Django = "^4.0.0"
+```
+
+The special keyword `latest` is also understood by the `@` operator:
+```shell
+poetry add django@latest
+```
+
+The above would translate to the following entry in `pyproject.toml`, assuming the latest release of `django` is `4.0.5`:
+```toml
+Django = "^4.0.5"
+```
+
+#### Extras
+
+Extras and `@` can be combined as one might expect (`package[extra]@version`):
+
+```shell
+poetry add django[bcrypt]@^4.0.0
+```
+
 ## `git` dependencies
 
 To depend on a library located in a `git` repository,