Write docs for `iced_winit`

3 files changed, 102 insertions, 4 deletions

diff --git a/winit/src/application.rs b/winit/src/application.rs
index bf41d0c8..4a5fd66b 100644
--- a/winit/src/application.rs
+++ b/winit/src/application.rs
@@ -6,19 +6,72 @@ use crate::{
     UserInterface,
 };
 
+/// An interactive, native cross-platform application.
+///
+/// This trait is the main entrypoint of Iced. Once implemented, you can run
+/// your GUI application by simply calling [`run`](#method.run). It will run in
+/// its own window.
+///
+/// An [`Application`](trait.Application.html) can execute asynchronous actions
+/// by returning a [`Command`](struct.Command.html) in some of its methods.
 pub trait Application: Sized {
+    /// The renderer to use to draw the [`Application`].
+    ///
+    /// [`Application`]: trait.Application.html
     type Renderer: Windowed;
 
+    /// The type of __messages__ your [`Application`] will produce.
+    ///
+    /// [`Application`]: trait.Application.html
     type Message: std::fmt::Debug + Send;
 
+    /// Initializes the [`Application`].
+    ///
+    /// Here is where you should return the initial state of your app.
+    ///
+    /// Additionally, you can return a [`Command`](struct.Command.html) if you
+    /// need to perform some async action in the background on startup. This is
+    /// useful if you want to load state from a file, perform an initial HTTP
+    /// request, etc.
+    ///
+    /// [`Application`]: trait.Application.html
     fn new() -> (Self, Command<Self::Message>);
 
+    /// Returns the current title of the [`Application`].
+    ///
+    /// This title can be dynamic! The runtime will automatically update the
+    /// title of your application when necessary.
+    ///
+    /// [`Application`]: trait.Application.html
     fn title(&self) -> String;
 
+    /// Handles a __message__ and updates the state of the [`Application`].
+    ///
+    /// This is where you define your __update logic__. All the __messages__,
+    /// produced by either user interactions or commands, will be handled by
+    /// this method.
+    ///
+    /// Any [`Command`] returned will be executed immediately in the background.
+    ///
+    /// [`Application`]: trait.Application.html
+    /// [`Command`]: struct.Command.html
     fn update(&mut self, message: Self::Message) -> Command<Self::Message>;
 
-    fn view(&mut self) -> Element<Self::Message, Self::Renderer>;
-
+    /// Returns the widgets to display in the [`Application`].
+    ///
+    /// These widgets can produce __messages__ based on user interaction.
+    ///
+    /// [`Application`]: trait.Application.html
+    fn view(&mut self) -> Element<'_, Self::Message, Self::Renderer>;
+
+    /// Runs the [`Application`].
+    ///
+    /// This method will take control of the current thread and __will NOT
+    /// return__.
+    ///
+    /// It should probably be that last thing you call in your `main` function.
+    ///
+    /// [`Application`]: trait.Application.html
     fn run()
     where
         Self: 'static,
diff --git a/winit/src/conversion.rs b/winit/src/conversion.rs
index e73fa008..03d583fb 100644
--- a/winit/src/conversion.rs
+++ b/winit/src/conversion.rs
@@ -1,6 +1,16 @@
-use crate::input::{keyboard::KeyCode, mouse, ButtonState};
-use crate::MouseCursor;
+//! Convert [`winit`] types to [`iced_native`] types, and viceversa.
+//!
+//! [`winit`]: https://github.com/rust-windowing/winit
+//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
+use crate::{
+    input::{keyboard::KeyCode, mouse, ButtonState},
+    MouseCursor,
+};
 
+/// Convert a `MouseCursor` from [`iced_native`] to a [`winit`] cursor icon.
+///
+/// [`winit`]: https://github.com/rust-windowing/winit
+/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
 pub fn mouse_cursor(mouse_cursor: MouseCursor) -> winit::window::CursorIcon {
     match mouse_cursor {
         MouseCursor::OutOfBounds => winit::window::CursorIcon::Default,
@@ -13,6 +23,10 @@ pub fn mouse_cursor(mouse_cursor: MouseCursor) -> winit::window::CursorIcon {
     }
 }
 
+/// Convert a `MouseButton` from [`winit`] to an [`iced_native`] mouse button.
+///
+/// [`winit`]: https://github.com/rust-windowing/winit
+/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
 pub fn mouse_button(mouse_button: winit::event::MouseButton) -> mouse::Button {
     match mouse_button {
         winit::event::MouseButton::Left => mouse::Button::Left,
@@ -22,6 +36,10 @@ pub fn mouse_button(mouse_button: winit::event::MouseButton) -> mouse::Button {
     }
 }
 
+/// Convert an `ElementState` from [`winit`] to an [`iced_native`] button state.
+///
+/// [`winit`]: https://github.com/rust-windowing/winit
+/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
 pub fn button_state(element_state: winit::event::ElementState) -> ButtonState {
     match element_state {
         winit::event::ElementState::Pressed => ButtonState::Pressed,
@@ -29,6 +47,10 @@ pub fn button_state(element_state: winit::event::ElementState) -> ButtonState {
     }
 }
 
+/// Convert a `VirtualKeyCode` from [`winit`] to an [`iced_native`] key code.
+///
+/// [`winit`]: https://github.com/rust-windowing/winit
+/// [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
 pub fn key_code(virtual_keycode: winit::event::VirtualKeyCode) -> KeyCode {
     match virtual_keycode {
         winit::event::VirtualKeyCode::Key1 => KeyCode::Key1,
diff --git a/winit/src/lib.rs b/winit/src/lib.rs
index a708b1bd..0a2bf7dd 100644
--- a/winit/src/lib.rs
+++ b/winit/src/lib.rs
@@ -1,3 +1,26 @@
+//! A windowing shell for Iced, on top of [`winit`].
+//!
+//! ![`iced_winit` crate graph](https://github.com/hecrj/iced/blob/cae26cb7bc627f4a5b3bcf1cd023a0c552e8c65e/docs/graphs/winit.png?raw=true)
+//!
+//! `iced_winit` offers some convenient abstractions on top of [`iced_native`]
+//! to quickstart development when using [`winit`].
+//!
+//! It exposes a renderer-agnostic [`Application`] trait that can be implemented
+//! and then run with a simple call. The use of this trait is optional.
+//!
+//! Additionally, a [`conversion`] module is available for users that decide to
+//! implement a custom event loop.
+//!
+//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native
+//! [`winit`]: https://github.com/rust-windowing/winit
+//! [`Application`]: trait.Application.html
+//! [`conversion`]: conversion
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
+#![deny(unused_results)]
+#![deny(unsafe_code)]
+#![deny(rust_2018_idioms)]
+
 #[doc(no_inline)]
 pub use iced_native::*;
 pub use winit;