docs: update info on Cargo workspace object

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

3 files changed, 36 insertions, 9 deletions

diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md
index 0c576ece6..ee800441e 100644
--- a/docs/markdown/Rust-module.md
+++ b/docs/markdown/Rust-module.md
@@ -16,8 +16,8 @@ authors:
 
 The rust module provides helper to integrate rust code into Meson. The
 goal is to make using rust in Meson more pleasant, while still
-remaining mesonic, this means that it attempts to make Rust work more
-like Meson, rather than Meson work more like rust.
+remaining mesonic. Rust conventions are adopted in order to help the
+Meson user and Rust developer, rather than to make Meson work more like rust.
 
 ## Functions
 
@@ -337,6 +337,13 @@ Returns all defined features for a specific package or subproject.
 
 ### Packages only
 
+Package objects are able to extract information from `Cargo.toml` files,
+and provide methods to query how Cargo would build this package.  They
+also contain convenience wrappers for non-Rust-specific functions
+(`executable`, `library`, `meson.override_dependency`, etc.), that
+automatically add dependencies and compiler arguments from `Cargo.toml`
+information.
+
 #### package.rust_args()
 
 ```meson
diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md
index c93eadf02..1ca3d3a85 100644
--- a/docs/markdown/Rust.md
+++ b/docs/markdown/Rust.md
@@ -137,9 +137,28 @@ cargo_ws = rustmod.workspace(
     features: ['feature1', 'feature2'])
 ```
 
-### Limitations
+Finally, the workspace object is able to build targets specified in `lib`
+or `bin` sections, extracting compiler arguments for dependencies and
+diagnostics from the Cargo.toml file.  The simplest case is that of building
+a simple binary crate:
 
-All your own crates must be built using the usual Meson functions such as
-[[static_library]] or [[executable]].  In the future, workspace object
-functionality will be extended to help building rustc command lines
-based on features, dependency names, and so on.
+```meson
+cargo_ws.package().executable(install: true)
+```
+
+For a workspace:
+
+```meson
+pkg_lib = cargo_ws.package('myproject-lib')
+lib = pkg_lib.library(install: false)
+pkg_lib.override_dependency(declare_dependency(link_with: lib))
+
+cargo_ws.package().executable(install: true)
+```
+
+Sources are automatically discovered, but can be specified as a
+[[@structured_src]] if they are partly generated.
+
+It is still possible to use keyword arguments to link non-Rust build targets,
+or even to use the usual Meson functions such as [[static_library]] or
+[[executable]].
diff --git a/docs/markdown/snippets/cargo-workspace-object.md b/docs/markdown/snippets/cargo-workspace-object.md
index c6bc4d4ba..1ef767529 100644
--- a/docs/markdown/snippets/cargo-workspace-object.md
+++ b/docs/markdown/snippets/cargo-workspace-object.md
@@ -6,8 +6,9 @@ This guarantees that features are resolved according to what is
 in the `Cargo.toml` file, and in fact enables configuration of
 features for the build.
 
-The returned object also allows retrieving features and dependencies
-for Cargo subprojects.
+The returned object allows retrieving features and dependencies
+for Cargo subprojects, and contains method to build targets
+declared in `Cargo.toml` files.
 
 While Cargo subprojects remain experimental, the Meson project will
 try to keep the workspace object reasonably backwards-compatible.