Finish docs cleanup

masonry/src/text/styleset.rs

@@ -1,3 +1,6 @@
+// Copyright 2018 the Xilem Authors and the Druid Authors
+// SPDX-License-Identifier: Apache-2.0
+
 use std::{collections::HashMap, mem::Discriminant};
 
 type StyleProperty<Brush> = parley::StyleProperty<'static, Brush>;

masonry/src/widget/prose.rs

@@ -18,20 +18,22 @@ use super::{Padding, TextArea, WidgetPod};
 /// Added padding between each horizontal edge of the widget
 /// and the text in logical pixels.
 ///
-/// This gives the text the smallest amount of breathing room.
+/// This gives the text the some slight breathing room.
 const PROSE_PADDING: Padding = Padding::horizontal(2.0);
 
 /// The prose widget displays immutable text which can be
 /// selected within.
 ///
 /// The text can also be copied from, but cannot be modified by the user.
-/// Note that copying is not yet integrated.
+/// Note that copying is not yet implemented.
 ///
 /// At runtime, most properties of the text will be set using [`text_mut`](Self::text_mut).
-/// This is because `Prose` largely serves as a wrapper around [`TextArea`].
+/// This is because `Prose` largely serves as a wrapper around a [`TextArea`].
 ///
-/// This should be preferred over [`Label`](super::Label) for most
-/// immutable text, other than that within other widgets.
+/// This should be used instead of [`Label`](super::Label) for immutable text,
+/// as it enables users to copy/paste from the text.
+///
+/// This widget has no actions.
 pub struct Prose {
     text: WidgetPod<TextArea<false>>,
 
@@ -58,37 +60,45 @@ impl Prose {
 
     /// Create a new `Prose` from a styled text area in a [`WidgetPod`].
     ///
-    /// Note that the default padding used for prose will not apply.
+    /// Note that the default padding used for prose will not be applied.
     pub fn from_text_region_pod(text: WidgetPod<TextArea<false>>) -> Self {
         Self { text, clip: false }
     }
 
-    /// Read the underlying text region. Useful for getting its ID.
-    pub fn region_pod(&self) -> &WidgetPod<TextArea<false>> {
-        &self.text
-    }
-
-    /// Whether to clip the text.
+    /// Whether to clip the text to the available space.
     ///
     /// If this is set to true, it is recommended, but not required, that this
     /// wraps a text area with [word wrapping](TextArea::with_word_wrap) enabled.
+    ///
+    /// To modify this on active prose, use [`set_clip`](Self::set_clip).
     pub fn with_clip(mut self, clip: bool) -> Self {
         self.clip = clip;
         self
     }
+
+    /// Read the underlying text region. Useful for getting its ID.
+    // This is a bit of a hack, to work around `from_text_region_pod` not being
+    // able to set padding.
+    pub fn region_pod(&self) -> &WidgetPod<TextArea<false>> {
+        &self.text
+    }
 }
 
 // --- MARK: WIDGETMUT ---
 impl Prose {
     /// Edit the underlying text area.
     ///
-    /// If this is set to true, it is recommended, but not required, that this
-    /// wraps a text area with [word wrapping](TextArea::set_word_wrap) enabled.
+    /// Used to modify most properties of the text.
     pub fn text_mut<'t>(this: &'t mut WidgetMut<'_, Self>) -> WidgetMut<'t, TextArea<false>> {
         this.ctx.get_mut(&mut this.widget.text)
     }
 
-    /// The runtime requivalent of [`with_hint`](Self::with_hint).
+    /// Whether to clip the text to the available space.
+    ///
+    /// If this is set to true, it is recommended, but not required, that this
+    /// wraps a text area with [word wrapping](TextArea::set_word_wrap) enabled.
+    ///
+    /// The runtime requivalent of [`with_clip`](Self::with_clip).
     pub fn set_clip(this: &mut WidgetMut<'_, Self>, clip: bool) {
         this.widget.clip = clip;
         this.ctx.request_layout();

masonry/src/widget/text_area.rs

@@ -1,8 +1,6 @@
 // Copyright 2018 the Xilem Authors and the Druid Authors
 // SPDX-License-Identifier: Apache-2.0
 
-#![warn(missing_docs)]
-
 use std::mem::Discriminant;
 use std::time::Instant;
 
@@ -38,6 +36,11 @@ use crate::{
 /// edited by the user of the app.
 /// This is true for `Textbox` and false for `Prose`.
 ///
+/// This widget emits the following actions only when `USER_EDITABLE` is true:
+///
+/// - `TextEntered`, which is sent when the enter key is pressed
+/// - `TextChanged`, which is sent whenever the text is changed
+///
 /// The exact semantics of how much horizontal space this widget takes up has not been determined.
 /// In particular, this has consequences when the alignment is set.
 // TODO: RichTextBox 👀

masonry/src/widget/textbox.rs

@@ -22,13 +22,21 @@ use super::{Padding, TextArea, WidgetPod};
 /// This makes it so that the surrounding box isn't crowding out the text.
 const TEXTBOX_PADDING: Padding = Padding::all(5.0);
 
-/// The margin added around textboxes to allow the boundaries to visible inside the window edge.
+/// The margin added around textboxes to allow the boundaries to be visible inside the window edge.
 const TEXTBOX_MARGIN: Padding = Padding::horizontal(2.0);
 
+/// The textbox widget displays text which can be edited by the user,
+/// inside a surrounding box.
 ///
-/// At runtime, most properties of the text will be set using [`text_mut`](Self::text_mut).
-/// This is because `Prose` largely serves as a wrapper around [`TextArea`].
+/// This currently does not support newlines entered by the user,
+/// although pre-existing newlines are handled correctly.
+///
+/// This widget itself does not emit any actions.
+/// However, the child widget will do so, as it is user editable.
+/// The ID of the child can be accessed using [`region_pod`](Self::region_pod).
 ///
+/// At runtime, most properties of the text will be set using [`text_mut`](Self::text_mut).
+/// This is because `Textbox` largely serves as a wrapper around a [`TextArea`].
 pub struct Textbox {
     text: WidgetPod<TextArea<true>>,
 
@@ -60,34 +68,40 @@ impl Textbox {
         Self { text, clip: false }
     }
 
-    /// Read the underlying text region.
-    ///
-    /// Useful for getting its ID, as most actions from the textbox will be sent by the child.
-    pub fn region_pod(&self) -> &WidgetPod<TextArea<true>> {
-        &self.text
-    }
-
-    /// Whether to clip the text.
+    /// Whether to clip the text to the drawn boundaries.
     ///
     /// If this is set to true, it is recommended, but not required, that this
     /// wraps a text area with [word wrapping](TextArea::with_word_wrap) enabled.
+    ///
+    /// To modify this on active textbox, use [`set_clip`](Self::set_clip).
     pub fn with_clip(mut self, clip: bool) -> Self {
         self.clip = clip;
         self
     }
+
+    /// Read the underlying text region.
+    ///
+    /// Useful for getting its ID, as most actions from the textbox will be sent by the child.
+    pub fn region_pod(&self) -> &WidgetPod<TextArea<true>> {
+        &self.text
+    }
 }
 
 // --- MARK: WIDGETMUT ---
 impl Textbox {
     /// Edit the underlying text area.
     ///
-    /// If this is set to true, it is recommended, but not required, that this
-    /// wraps a text area with [word wrapping](TextArea::set_word_wrap) enabled.
+    /// Used to modify most properties of the text.
     pub fn text_mut<'t>(this: &'t mut WidgetMut<'_, Self>) -> WidgetMut<'t, TextArea<true>> {
         this.ctx.get_mut(&mut this.widget.text)
     }
 
-    /// The runtime requivalent of [`with_hint`](Self::with_hint).
+    /// Whether to clip the text to the drawn boundaries.
+    ///
+    /// If this is set to true, it is recommended, but not required, that this
+    /// wraps a text area with [word wrapping](TextArea::set_word_wrap) enabled.
+    ///
+    /// The runtime requivalent of [`with_clip`](Self::with_clip).
     pub fn set_clip(this: &mut WidgetMut<'_, Self>, clip: bool) {
         this.widget.clip = clip;
         this.ctx.request_layout();