Supplement image widget docs

CHANGELOG.md

@@ -25,6 +25,7 @@ You can find its changes [documented below](#060---2020-06-01).
 
 ### Docs
 
+- Added documentation for the `druid::Image` widget. ([#1018] by [@covercash2])
 - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2])
 
 ### Examples
@@ -319,6 +320,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
 
 [Unreleased]: https://github.com/xi-editor/druid/compare/v0.6.0...master
 [0.6.0]: https://github.com/xi-editor/druid/compare/v0.5.0...v0.6.0

druid/src/widget/image.rs

@@ -25,7 +25,52 @@ use crate::{
     PaintCtx, Rect, RenderContext, Size, UpdateCtx, Widget,
 };
 
-/// A widget that renders an Image
+/// A widget that renders a bitmap Image.
+///
+/// Contains data about how to fill given space and interpolate pixels.
+/// Configuration options are provided via the builder pattern.
+///
+/// Note: interpolation can lead to blurry or pixelated images and so is not
+/// recommended for things like icons. Instead consider using
+/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics)
+/// 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 fill strategy
+///     .fill_mode(FillStrat::Fill)
+///     // set interpolation mode
+///     .interpolation_mode(InterpolationMode::NearestNeighbor);
+/// ```
+/// 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 fill strategy
+/// image_widget.set_fill_mode(FillStrat::FitWidth);
+/// // set interpolation mode
+/// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor);
+/// ```
 pub struct Image {
     image_data: ImageData,
     fill: FillStrat,
@@ -35,7 +80,10 @@ 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`])
     pub fn new(image_data: ImageData) -> Self {
         Image {
             image_data,
@@ -50,7 +98,7 @@ impl Image {
         self
     }
 
-    /// Modify the widget's `FillStrat`.
+    /// Modify the widget's [`FillStrat`].
     pub fn set_fill_mode(&mut self, newfil: FillStrat) {
         self.fill = newfil;
     }
@@ -61,7 +109,7 @@ impl Image {
         self
     }
 
-    /// Modify the widget's `InterpolationMode`.
+    /// Modify the widget's [`InterpolationMode`].
     pub fn set_interpolation_mode(&mut self, interpolation: InterpolationMode) {
         self.interpolation = interpolation;
     }
@@ -106,7 +154,14 @@ impl<T: Data> Widget<T> for Image {
     }
 }
 
-/// Stored Image data.
+/// Loaded image data.
+///
+/// By default, Druid does not parse image data.
+/// However, [enabling the `image` feature](../index.html#optional-features)
+/// provides several
+/// methods by which you can load image files.
+///
+/// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]).
 #[derive(Clone)]
 pub struct ImageData {
     pixels: Vec<u8>,