Merge pull request #65 from hecrj/improvement/docs

Documentation

core/src/align.rs

@@ -1,18 +1,38 @@
-/// Alignment on the cross axis of a container.
-///
-///   * On a [`Column`], it describes __horizontal__ alignment.
-///   * On a [`Row`], it describes __vertical__ alignment.
-///
-/// [`Column`]: widget/struct.Column.html
-/// [`Row`]: widget/struct.Row.html
+/// Alignment on an axis of a container.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Align {
-    /// Align at the start of the cross axis.
+    /// Align at the start of the axis.
     Start,
 
-    /// Align at the center of the cross axis.
+    /// Align at the center of the axis.
     Center,
 
-    /// Align at the end of the cross axis.
+    /// Align at the end of the axis.
     End,
 }
+
+/// The horizontal alignment of some resource.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum HorizontalAlignment {
+    /// Align left
+    Left,
+
+    /// Horizontally centered
+    Center,
+
+    /// Align right
+    Right,
+}
+
+/// The vertical alignment of some resource.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum VerticalAlignment {
+    /// Align top
+    Top,
+
+    /// Vertically centered
+    Center,
+
+    /// Align bottom
+    Bottom,
+}

core/src/background.rs

@@ -1,7 +1,9 @@
 use crate::Color;
 
+/// The background of some element.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Background {
+    /// A solid color
     Color(Color),
     // TODO: Add gradient and image variants
 }

core/src/color.rs

@@ -25,6 +25,9 @@ impl Color {
         a: 1.0,
     };
 
+    /// Converts the [`Color`] into its linear values.
+    ///
+    /// [`Color`]: struct.Color.html
     pub fn into_linear(self) -> [f32; 4] {
         // As described in:
         // https://en.wikipedia.org/wiki/SRGB#The_reverse_transformation

core/src/command.rs

@@ -1,16 +1,30 @@
 use futures::future::{BoxFuture, Future, FutureExt};
 
+/// A collection of async operations.
+///
+/// You should be able to turn a future easily into a [`Command`], either by
+/// using the `From` trait or [`Command::perform`].
+///
+/// [`Command`]: struct.Command.html
 pub struct Command<T> {
     futures: Vec<BoxFuture<'static, T>>,
 }
 
 impl<T> Command<T> {
+    /// Creates an empty [`Command`].
+    ///
+    /// In other words, a [`Command`] that does nothing.
+    ///
+    /// [`Command`]: struct.Command.html
     pub fn none() -> Self {
         Self {
             futures: Vec::new(),
         }
     }
 
+    /// Creates a [`Command`] that performs the action of the given future.
+    ///
+    /// [`Command`]: struct.Command.html
     pub fn perform<A>(
         future: impl Future<Output = T> + 'static + Send,
         f: impl Fn(T) -> A + 'static + Send,
@@ -20,12 +34,21 @@ impl<T> Command<T> {
         }
     }
 
+    /// Creates a [`Command`] that performs the actions of all the givens
+    /// futures.
+    ///
+    /// Once this command is run, all the futures will be exectued at once.
+    ///
+    /// [`Command`]: struct.Command.html
     pub fn batch(commands: impl Iterator<Item = Command<T>>) -> Self {
         Self {
             futures: commands.flat_map(|command| command.futures).collect(),
         }
     }
 
+    /// Converts a [`Command`] into its underlying list of futures.
+    ///
+    /// [`Command`]: struct.Command.html
     pub fn futures(self) -> Vec<BoxFuture<'static, T>> {
         self.futures
     }

core/src/font.rs

@@ -1,8 +1,18 @@
+/// A font.
 #[derive(Debug, Clone, Copy)]
 pub enum Font {
+    /// The default font.
+    ///
+    /// This is normally a font configured in a renderer or loaded from the
+    /// system.
     Default,
+
+    /// An external font.
     External {
+        /// The name of the external font
         name: &'static str,
+
+        /// The bytes of the external font
         bytes: &'static [u8],
     },
 }

core/src/length.rs

@@ -1,12 +1,24 @@
 /// The strategy used to fill space in a specific dimension.
 #[derive(Debug, Clone, Copy, PartialEq, Hash)]
 pub enum Length {
+    /// Fill all the remaining space
     Fill,
+
+    /// Fill the least amount of space
     Shrink,
+
+    /// Fill a fixed amount of space
     Units(u16),
 }
 
 impl Length {
+    /// Returns the _fill factor_ of the [`Length`].
+    ///
+    /// The _fill factor_ is a relative unit describing how much of the
+    /// remaining space should be filled when compared to other elements. It
+    /// is only meant to be used by layout engines.
+    ///
+    /// [`Length`]: enum.Length.html
     pub fn fill_factor(&self) -> u16 {
         match self {
             Length::Fill => 1,

core/src/lib.rs

@@ -1,24 +1,40 @@
-pub mod widget;
+//! The core library of [Iced].
+//!
+//! ![`iced_core` crate graph](https://github.com/hecrj/iced/blob/cae26cb7bc627f4a5b3bcf1cd023a0c552e8c65e/docs/graphs/core.png?raw=true)
+//!
+//! This library holds basic types that can be reused and re-exported in
+//! different runtime implementations. For instance, both [`iced_native`] and
+//! [`iced_web`] are built on top of `iced_core`.
+//!
+//! [Iced]: https://github.com/hecrj/iced
+//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
+//! [`iced_web`]: https://github.com/hecrj/iced/tree/master/web
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
+#![deny(unused_results)]
+#![deny(unsafe_code)]
+#![deny(rust_2018_idioms)]
 
 mod align;
 mod background;
 mod color;
-#[cfg(feature = "command")]
-mod command;
 mod font;
 mod length;
 mod point;
 mod rectangle;
 mod vector;
 
-pub use align::Align;
+pub use align::{Align, HorizontalAlignment, VerticalAlignment};
 pub use background::Background;
 pub use color::Color;
-#[cfg(feature = "command")]
-pub use command::Command;
 pub use font::Font;
 pub use length::Length;
 pub use point::Point;
 pub use rectangle::Rectangle;
 pub use vector::Vector;
-pub use widget::*;
+
+#[cfg(feature = "command")]
+mod command;
+
+#[cfg(feature = "command")]
+pub use command::Command;

core/src/vector.rs

@@ -1,7 +1,14 @@
 /// A 2D vector.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Vector<T = f32> {
+    /// The X component of the [`Vector`]
+    ///
+    /// [`Vector`]: struct.Vector.html
     pub x: T,
+
+    /// The Y component of the [`Vector`]
+    ///
+    /// [`Vector`]: struct.Vector.html
     pub y: T,
 }