Improve Env docs

druid/src/env.rs

@@ -35,6 +35,18 @@ use crate::{Color, Data, Point, Rect, Size};
 /// example of the latter is setting a value for enabled/disabled status
 /// so that an entire subtree can be disabled ("grayed out") with one
 /// setting.
+///
+/// [`EnvScope`] can be used to override parts of `Env` for its descendants.
+///
+/// # Important
+/// It is the programmer's responsibility to ensure that the environment
+/// is used correctly. See [`Key`] for an example.
+/// - [`Key`]s should be `const`s with unique names
+/// - [`Key`]s must always be set before they are used.
+/// - Values can only be overwritten by values of the same type.
+///
+/// [`EnvScope`]: widget/struct.EnvScope.html
+/// [`Key`]: struct.Key.html
 #[derive(Clone)]
 pub struct Env(Arc<EnvImpl>);
 
@@ -51,6 +63,27 @@ struct EnvImpl {
 /// implements [`ValueType`]. For "expensive" types, this is a reference,
 /// so the type for a string is `Key<&str>`.
 ///
+/// # Examples
+///
+/// ```
+///# use druid::{Key, Color, WindowDesc, AppLauncher, widget::Label};
+/// const IMPORTANT_LABEL_COLOR: Key<Color> = Key::new("my-app.important-label-color");
+///
+/// fn important_label() -> Label<()> {
+///     Label::new("Warning!").with_text_color(IMPORTANT_LABEL_COLOR)
+/// }
+///
+/// fn main() {
+///     let main_window = WindowDesc::new(important_label);
+///
+///     AppLauncher::with_window(main_window)
+///         .configure_env(|env, _state| {
+///             // The `Key` must be set before it is used.
+///             env.set(IMPORTANT_LABEL_COLOR, Color::rgb(1.0, 0.0, 0.0));
+///         });
+/// }
+/// ```
+///
 /// [`ValueType`]: trait.ValueType.html
 /// [`Env`]: struct.Env.html
 pub struct Key<T> {

druid/src/widget/env_scope.rs

@@ -27,18 +27,18 @@ pub struct EnvScope<T, W> {
 }
 
 impl<T, W> EnvScope<T, W> {
-    /// Create a widget that updates the environment for its child.
+    /// Create a widget that updates the environment for its descendants.
     ///
     /// Accepts a closure that sets Env values.
     ///
+    /// This is available as [`WidgetExt::env_scope`] for convenience
+    ///
     /// # Examples
     /// ```
     /// # use druid::{theme, Widget};
     /// # use druid::piet::{Color};
     /// # use druid::widget::{Label, EnvScope};
-    ///
     /// # fn build_widget() -> impl Widget<String> {
-    ///
     /// EnvScope::new(
     ///     |env, data| {
     ///         env.set(theme::LABEL_COLOR, Color::WHITE);
@@ -48,6 +48,8 @@ impl<T, W> EnvScope<T, W> {
     ///
     /// # }
     /// ```
+    ///
+    /// [`WidgetExt::env_scope`]: ../trait.WidgetExt.html#method.env_scope
     pub fn new(f: impl Fn(&mut Env, &T) + 'static, child: W) -> EnvScope<T, W> {
         EnvScope {
             f: Box::new(f),

druid/src/widget/widget_ext.rs

@@ -244,6 +244,7 @@ impl<T: Data> SizedBox<T> {
 }
 
 // if two things are modifying an env one after another, just combine the modifications
+#[doc(hidden)]
 impl<T: Data, W> EnvScope<T, W> {
     pub fn env_scope(self, f2: impl Fn(&mut Env, &T) + 'static) -> EnvScope<T, W> {
         let EnvScope { f, child } = self;