Attempt to document Result/Option.

docs/rust/std.md

@@ -56,4 +56,43 @@ Allowing for C++ to call it:
 
 ```c++
 append_to_rust_string(s, " I'm a neat addition");
-```
+```
+
+## `Result`
+
+The Rust `Result<T, E>` generic receives Rust bindings as `rs_std::Result<T,
+E>`, so long as both `T` and `E` are non-ZST types supported by Crubit.
+
+`rs_std::Result<T, E>` has a similar API to
+[`std::expected`](https://en.cppreference.com/cpp/utility/expected).
+(Alternatively, it has a similar API to
+[`std::optional`](https://en.cppreference.com/cpp/utility/optional), but with an
+additional error payload.) If `has_value()` returns `false`, then `error()` will
+return a reference to the error payload of type `E`.
+
+```c++
+if (myresult.has_value()) {
+  Foo(*myresult);
+} else {
+  Foo(myresult.error());
+}
+```
+
+A more complete description of the API is in the common `ResultBase` public base
+class: support/rs_std/result.h
+
+## `Option`
+
+The Rust `Option<T>` generic receives Rust bindings as `rs_std::Option<T>`, so
+long as `T` is a non-ZST type supported by Crubit. It has a similar API to
+[`std::optional`](https://en.cppreference.com/cpp/utility/optional), and
+implicitly converts to and from `std::optional`.
+
+```c++
+if (myoption.has_value()) {
+  Foo(*myoption);
+}
+```
+
+A more complete description of the API is in the common `OptionBase` public base
+class: support/rs_std/option.h

examples/rust/std/BUILD

@@ -0,0 +1,45 @@
+load("@rules_cc//cc:cc_binary.bzl", "cc_binary")
+load(
+    "@rules_rust//rust:defs.bzl",
+    "rust_library",
+)
+load(
+    "//cc_bindings_from_rs/bazel_support:cc_bindings_from_rust_rule.bzl",
+    "cc_bindings_from_rust",
+)
+load(
+    "//cc_bindings_from_rs/test/golden:golden_test.bzl",
+    "golden_test",
+)
+
+package(default_applicable_licenses = ["//:license"])
+
+licenses(["notice"])
+
+# This declares an "example_crate_cc_api" target that provides Crubit-generated
+# C++ bindings for the Rust crate behind the `":example_crate"` target.
+rust_library(
+    name = "example_crate",
+    srcs = ["example.rs"],
+)
+
+cc_bindings_from_rust(
+    name = "example_crate_cc_api",
+    crate = ":example_crate",
+)
+
+cc_binary(
+    name = "main",
+    srcs = ["main.cc"],
+    deps = [
+        ":example_crate_cc_api",
+        "//support/rs_std:rs_alloc",
+        "//support/rs_std:str_ref",
+    ],
+)
+
+golden_test(
+    name = "example_golden_test",
+    golden_h = "example_generated.h",
+    rust_library = "example_crate",
+)

examples/rust/std/example.rs

@@ -0,0 +1,11 @@
+// Part of the Crubit project, under the Apache License v2.0 with LLVM
+// Exceptions. See /LICENSE for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+pub fn returns_result(is_ok: bool) -> Result<Option<&'static str>, String> {
+    if is_ok {
+        Ok(Some("hello world!"))
+    } else {
+        Err("goodbye, cruel world!".to_string())
+    }
+}