Supplement image widget docs (#1018)

CHANGELOG.md

@@ -32,6 +32,7 @@ You can find its changes [documented below](#060---2020-06-01).
 
 ### Docs
 
+- Added documentation for the `Image` widget. ([#1018] by [@covercash2])
 - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2])
 
 ### Examples
@@ -328,6 +329,7 @@ Last release without a changelog :(
 [#1008]: https://github.com/xi-editor/druid/pull/1008
 [#1011]: https://github.com/xi-editor/druid/pull/1011
 [#1013]: https://github.com/xi-editor/druid/pull/1013
+[#1018]: https://github.com/xi-editor/druid/pull/1018
 [#1025]: https://github.com/xi-editor/druid/pull/1025
 [#1028]: https://github.com/xi-editor/druid/pull/1028
 [#1042]: https://github.com/xi-editor/druid/pull/1042

druid/src/widget/image.rs

@@ -25,7 +25,58 @@ use crate::{
     RenderContext, Size, UpdateCtx, Widget,
 };
 
-/// A widget that renders an Image
+/// A widget that renders a bitmap Image.
+///
+/// Contains data about how to fill the given space and interpolate pixels.
+/// Configuration options are provided via the builder pattern.
+///
+/// Note: when [scaling a bitmap image], such as supporting multiple
+/// screen sizes and resolutions, interpolation can lead to blurry
+/// or pixelated images and so is not recommended for things like icons.
+/// Instead consider using [SVG files] and enabling the `svg` feature with `cargo`.
+///
+/// (See also:
+/// [`ImageData`],
+/// [`FillStrat`],
+/// [`InterpolationMode`]
+/// )
+///
+/// # Example
+///
+/// Create an image widget and configure it using builder methods
+/// ```
+/// use druid::{
+///     widget::{Image, ImageData, FillStrat},
+///     piet::InterpolationMode,
+/// };
+///
+/// let image_data = ImageData::empty();
+/// let image_widget = Image::new(image_data)
+///     // set the fill strategy
+///     .fill_mode(FillStrat::Fill)
+///     // set the interpolation mode
+///     .interpolation_mode(InterpolationMode::Bilinear);
+/// ```
+/// Create an image widget and configure it using setters
+/// ```
+/// use druid::{
+///     widget::{Image, ImageData, FillStrat},
+///     piet::InterpolationMode,
+/// };
+///
+/// let image_data = ImageData::empty();
+/// let mut image_widget = Image::new(image_data);
+/// // set the fill strategy
+/// image_widget.set_fill_mode(FillStrat::FitWidth);
+/// // set the interpolation mode
+/// image_widget.set_interpolation_mode(InterpolationMode::Bilinear);
+/// ```
+///
+/// [scaling a bitmap image]: ../struct.Scale.html#pixels-and-display-points
+/// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
+/// [`ImageData`]: struct.ImageData.html
+/// [`FillStrat`]: ../widget/enum.FillStrat.html
+/// [`InterpolationMode`]: ../piet/enum.InterpolationMode.html
 pub struct Image {
     image_data: ImageData,
     paint_data: Option<PietImage>,
@@ -36,7 +87,13 @@ pub struct Image {
 impl Image {
     /// Create an image drawing widget from `ImageData`.
     ///
-    /// The Image will scale to fit its box constraints.
+    /// By default, the Image will scale to fit its box constraints
+    /// ([`FillStrat::Fill`])
+    /// and will be scaled bilinearly
+    /// ([`InterpolationMode::Bilinear`])
+    ///
+    /// [`FillStrat::Fill`]: ../widget/enum.FillStrat.html#variant.Fill
+    /// [`InterpolationMode::Bilinear`]: ../piet/enum.InterpolationMode.html#variant.Bilinear
     pub fn new(image_data: ImageData) -> Self {
         Image {
             image_data,
@@ -52,7 +109,7 @@ impl Image {
         self
     }
 
-    /// Modify the widget's `FillStrat`.
+    /// Modify the widget's fill strategy.
     pub fn set_fill_mode(&mut self, newfil: FillStrat) {
         self.fill = newfil;
         self.paint_data = None;
@@ -64,7 +121,7 @@ impl Image {
         self
     }
 
-    /// Modify the widget's `InterpolationMode`.
+    /// Modify the widget's interpolation mode.
     pub fn set_interpolation_mode(&mut self, interpolation: InterpolationMode) {
         self.interpolation = interpolation;
         self.paint_data = None;
@@ -122,7 +179,17 @@ impl<T: Data> Widget<T> for Image {
     }
 }
 
-/// Stored Image data.
+/// Processed image data.
+///
+/// By default, Druid does not parse image data.
+/// However, enabling [the `image` feature]
+/// provides several
+/// methods by which you can load image files.
+///
+/// Contains raw bytes, dimensions, and image format ([`piet::ImageFormat`]).
+///
+/// [the `image` feature]: ../index.html#optional-features
+/// [`piet::ImageFormat`]: ../piet/enum.ImageFormat.html
 #[derive(Clone)]
 pub struct ImageData {
     pixels: Vec<u8>,