docs: update info on Cargo workspace object

Author: bonzini

docs/markdown/Rust-module.md

@@ -335,6 +335,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

docs/markdown/Rust.md

@@ -133,13 +133,29 @@ The workspace object also enables configuration of Cargo features, for example
 from Meson options:
 
 ```meson
-ws = rust.workspace(
+cargo = rust.workspace(
     features: ['feature1', 'feature2'])
 ```
 
-### Limitations
+Finally, the workspace object is able to build targets specified in `[lib]`
+or `[[bins]]` 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.package().executable(install: true)
+```
+
+Or for a workspace:
+
+```meson
+cargo.package('myproject-lib').library(install: false)
+cargo.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]].

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.