From 631c9e4a215d8f044d76ea926117f9a9bdd24d5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Fri, 6 Nov 2020 02:25:56 +0100 Subject: [PATCH] Write missing documentation in `iced_winit` --- glutin/src/application.rs | 3 +- winit/src/application.rs | 16 +++++++++- winit/src/application/state.rs | 54 ++++++++++++++++++++++++++++++++++ winit/src/lib.rs | 2 +- 4 files changed, 72 insertions(+), 3 deletions(-) diff --git a/glutin/src/application.rs b/glutin/src/application.rs index 26e7b852..68612978 100644 --- a/glutin/src/application.rs +++ b/glutin/src/application.rs @@ -1,9 +1,10 @@ //! Create interactive, native cross-platform applications. use crate::{mouse, Error, Executor, Runtime}; -pub use iced_winit::application::{self, Application}; +pub use iced_winit::Application; use iced_graphics::window; +use iced_winit::application; use iced_winit::conversion; use iced_winit::futures; use iced_winit::futures::channel::mpsc; diff --git a/winit/src/application.rs b/winit/src/application.rs index 8e97706f..c1d86471 100644 --- a/winit/src/application.rs +++ b/winit/src/application.rs @@ -377,8 +377,10 @@ async fn run_instance( drop(ManuallyDrop::into_inner(user_interface)); } -/// Returns true if the provided event should cause the [`Application`] to +/// Returns true if the provided event should cause an [`Application`] to /// exit. +/// +/// [`Application`]: trait.Application.html pub fn requests_exit( event: &winit::event::WindowEvent<'_>, _modifiers: winit::event::ModifiersState, @@ -401,6 +403,12 @@ pub fn requests_exit( } } +/// Builds a [`UserInterface`] for the provided [`Application`], logging +/// [`Debug`] information accordingly. +/// +/// [`UserInterface`]: struct.UserInterface.html +/// [`Application`]: trait.Application.html +/// [`Debug`]: struct.Debug.html pub fn build_user_interface<'a, A: Application>( application: &'a mut A, cache: Cache, @@ -419,6 +427,12 @@ pub fn build_user_interface<'a, A: Application>( user_interface } +/// Updates an [`Application`] by feeding it the provided messages, spawning any +/// resulting [`Command`], and tracking its [`Subscription`]. +/// +/// [`Application`]: trait.Application.html +/// [`Command`]: struct.Command.html +/// [`Subscription`]: struct.Subscription.html pub fn update( application: &mut A, runtime: &mut Runtime, A::Message>, diff --git a/winit/src/application/state.rs b/winit/src/application/state.rs index 1f3c77a0..4c0bfd34 100644 --- a/winit/src/application/state.rs +++ b/winit/src/application/state.rs @@ -5,6 +5,9 @@ use std::marker::PhantomData; use winit::event::WindowEvent; use winit::window::Window; +/// The state of a windowed [`Application`]. +/// +/// [`Application`]: ../trait.Application.html #[derive(Debug, Clone)] pub struct State { title: String, @@ -19,6 +22,10 @@ pub struct State { } impl State { + /// Creates a new [`State`] for the provided [`Application`] and window. + /// + /// [`State`]: struct.State.html + /// [`Application`]: ../trait.Application.html pub fn new(application: &A, window: &Window) -> Self { let title = application.title(); let mode = application.mode(); @@ -48,30 +55,61 @@ impl State { } } + /// Returns the current background [`Color`] of the [`State`]. + /// + /// [`Color`]: ../struct.Color.html + /// [`State`]: struct.State.html pub fn background_color(&self) -> Color { self.background_color } + /// Returns the current [`Viewport`] of the [`State`]. + /// + /// [`Viewport`]: ../struct.Viewport.html + /// [`State`]: struct.State.html pub fn viewport(&self) -> &Viewport { &self.viewport } + /// Returns the version of the [`Viewport`] of the [`State`]. + /// + /// The version is incremented every time the [`Viewport`] changes. + /// + /// [`Viewport`]: ../struct.Viewport.html + /// [`State`]: struct.State.html pub fn viewport_version(&self) -> usize { self.viewport_version } + /// Returns the physical [`Size`] of the [`Viewport`] of the [`State`]. + /// + /// [`Size`]: ../struct.Size.html + /// [`Viewport`]: ../struct.Viewport.html + /// [`State`]: struct.State.html pub fn physical_size(&self) -> Size { self.viewport.physical_size() } + /// Returns the logical [`Size`] of the [`Viewport`] of the [`State`]. + /// + /// [`Size`]: ../struct.Size.html + /// [`Viewport`]: ../struct.Viewport.html + /// [`State`]: struct.State.html pub fn logical_size(&self) -> Size { self.viewport.logical_size() } + /// Returns the current scale factor of the [`Viewport`] of the [`State`]. + /// + /// [`Viewport`]: ../struct.Viewport.html + /// [`State`]: struct.State.html pub fn scale_factor(&self) -> f64 { self.viewport.scale_factor() } + /// Returns the current cursor position of the [`State`]. + /// + /// [`State`]: struct.State.html pub fn cursor_position(&self) -> Point { conversion::cursor_position( self.cursor_position, @@ -79,10 +117,17 @@ impl State { ) } + /// Returns the current keyboard modifiers of the [`State`]. + /// + /// [`State`]: struct.State.html pub fn modifiers(&self) -> winit::event::ModifiersState { self.modifiers } + /// Processes the provided window event and updates the [`State`] + /// accordingly. + /// + /// [`State`]: struct.State.html pub fn update( &mut self, window: &Window, @@ -139,6 +184,15 @@ impl State { } } + /// Synchronizes the [`State`] with its [`Application`] and its respective + /// window. + /// + /// Normally an [`Application`] should be synchronized with its [`State`] + /// and window after calling [`Application::update`]. + /// + /// [`State`]: struct.State.html + /// [`Application`]: ../trait.Application.html + /// [`Application::update`]: ../trait.Application.html#tymethod.update pub fn synchronize(&mut self, application: &A, window: &Window) { // Update window title let new_title = application.title(); diff --git a/winit/src/lib.rs b/winit/src/lib.rs index 91e7774c..8ca8eec1 100644 --- a/winit/src/lib.rs +++ b/winit/src/lib.rs @@ -15,7 +15,7 @@ //! [`winit`]: https://github.com/rust-windowing/winit //! [`Application`]: trait.Application.html //! [`conversion`]: conversion -//#![deny(missing_docs)] +#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] #![forbid(unsafe_code)]