docs: App & AppBuilder comments

Author: MartinKavik

src/vdom.rs

@@ -151,7 +151,7 @@ where
     pub update: UpdateFn<Ms, Mdl, ElC, GMs>,
     pub sink: Option<SinkFn<Ms, Mdl, ElC, GMs>>,
     view: ViewFn<Mdl, ElC>,
-    window_events: Option<WindowEvents<Ms, Mdl>>,
+    window_events: Option<WindowEventsFn<Ms, Mdl>>,
 }
 
 pub struct UndefinedGMsg;
@@ -200,6 +200,33 @@ impl<Ms, Mdl, ElC: View<Ms> + 'static, GMs: 'static> App<Ms, Mdl, ElC, GMs> {
         Self::builder(update, view).init(Box::new(init))
     }
 
+    /// Creates a new `AppBuilder` instance. It's the standard way to create a Seed app.
+    ///
+    /// Then you can call optional builder methods like `routes` or `sink`.
+    /// And you have to call method `build_and_start` to build and run a new `App` instance.
+    ///
+    /// _NOTE:_ If your `Model` doesn't implement `Default`, you have to call builder method `after_mount`.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// fn update(msg: Msg, model: &mut Model, _orders: &mut impl Orders<Msg, GMsg>) {
+    ///    match msg {
+    ///        Msg::Clicked => model.clicks += 1,
+    ///    }
+    ///}
+    ///
+    /// fn view(model: &Model) -> impl View<Msg> {
+    ///    vec![
+    ///        button![
+    ///            format!("Clicked: {}", model.clicks),
+    ///            simple_ev(Ev::Click, Msg::Clicked),
+    ///        ],
+    ///    ]
+    ///}
+    ///
+    ///App::builder(update, view)
+    /// ```
     pub fn builder(
         update: UpdateFn<Ms, Mdl, ElC, GMs>,
         view: ViewFn<Mdl, ElC>,
@@ -222,7 +249,7 @@ impl<Ms, Mdl, ElC: View<Ms> + 'static, GMs: 'static> App<Ms, Mdl, ElC, GMs> {
         view: ViewFn<Mdl, ElC>,
         mount_point: Element,
         routes: Option<RoutesFn<Ms>>,
-        window_events: Option<WindowEvents<Ms, Mdl>>,
+        window_events: Option<WindowEventsFn<Ms, Mdl>>,
         init_cfg: OptDynInitCfg<Ms, Mdl, ElC, GMs>,
     ) -> Self {
         let window = util::window();

src/vdom/alias.rs

@@ -4,5 +4,5 @@ pub type UpdateFn<Ms, Mdl, ElC, GMs> = fn(Ms, &mut Mdl, &mut OrdersContainer<Ms,
 pub type SinkFn<Ms, Mdl, ElC, GMs> = fn(GMs, &mut Mdl, &mut OrdersContainer<Ms, Mdl, ElC, GMs>);
 pub type ViewFn<Mdl, ElC> = fn(&Mdl) -> ElC;
 pub type RoutesFn<Ms> = fn(routing::Url) -> Option<Ms>;
-pub type WindowEvents<Ms, Mdl> = fn(&Mdl) -> Vec<events::Listener<Ms>>;
+pub type WindowEventsFn<Ms, Mdl> = fn(&Mdl) -> Vec<events::Listener<Ms>>;
 pub type MsgListeners<Ms> = Vec<Box<dyn Fn(&Ms)>>;

src/vdom/builder.rs

@@ -346,13 +346,13 @@ impl InitAPIData for UndefinedInitAPI {
     }
 }
 
-/// Used to create and store initial app configuration, ie items passed by the app creator
+/// Used to create and store initial app configuration, ie items passed by the app creator.
 pub struct Builder<Ms: 'static, Mdl: 'static, ElC: View<Ms>, GMs, InitAPIType> {
     update: UpdateFn<Ms, Mdl, ElC, GMs>,
     view: ViewFn<Mdl, ElC>,
 
     routes: Option<RoutesFn<Ms>>,
-    window_events: Option<WindowEvents<Ms, Mdl>>,
+    window_events: Option<WindowEventsFn<Ms, Mdl>>,
     sink: Option<SinkFn<Ms, Mdl, ElC, GMs>>,
 
     // TODO: Remove when removing legacy init fields.
@@ -443,6 +443,19 @@ impl<
         }
     }
 
+    /// Select HTML element where the app will be mounted and how it'll be mounted.
+    ///
+    /// See `BeforeMount::mount_point` and `BeforeMount::mount_type` docs for more info.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///fn before_mount(_url: Url) -> BeforeMount {
+    ///    BeforeMount::new()
+    ///        .mount_point("main")
+    ///        .mount_type(MountType::Takeover)
+    ///}
+    /// ```
     pub fn before_mount(
         self,
         before_mount: impl FnOnce(routing::Url) -> BeforeMount + 'static,
@@ -459,10 +472,22 @@ impl<
         }
     }
 
-    pub fn after_mount<NewIAM: 'static + IntoAfterMount<Ms, Mdl, ElC, GMs>>(
+    /// You can create your `Model` and handle initial URL in this method.
+    ///
+    /// See `AfterMount::url_handling` for more info about initial URL handling.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///fn after_mount(_url: Url, _orders: &mut impl Orders<Msg, GMsg>) -> AfterMount<Model> {
+    ///    let model = Model { clicks: 0 };
+    ///    AfterMount::new(model).url_handling(UrlHandling::None)
+    ///}
+    /// ```
+    pub fn after_mount<AM: 'static + IntoAfterMount<Ms, Mdl, ElC, GMs>>(
         self,
-        after_mount: NewIAM,
-    ) -> Builder<Ms, Mdl, ElC, GMs, BeforeAfterInitAPI<NewIAM>> {
+        after_mount: AM,
+    ) -> Builder<Ms, Mdl, ElC, GMs, BeforeAfterInitAPI<AM>> {
         Builder {
             update: self.update,
             view: self.view,
@@ -476,13 +501,34 @@ impl<
     }
 
     /// Registers a function which maps URLs to messages.
+    ///
+    /// When you return `None`, Seed doesn't call your `update` function
+    /// and also doesn't push the new route or prevent page refresh.
+    /// It's useful if the user clicked on a link and Seed shouldn't intercept it,
+    /// because it's e.g. a download link.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///fn routes(url: Url) -> Option<Msg> {
+    ///    Some(Msg::UrlChanged(url))
+    ///}
+    /// ```
     pub fn routes(mut self, routes: RoutesFn<Ms>) -> Self {
         self.routes = Some(routes);
         self
     }
 
     /// Registers a function which decides how window events will be handled.
-    pub fn window_events(mut self, window_events: WindowEvents<Ms, Mdl>) -> Self {
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///fn window_events(_model: &Model) -> Vec<Listener<Msg>> {
+    ///    vec![keyboard_ev(Ev::KeyDown, Msg::KeyPressed)]
+    ///}
+    /// ```
+    pub fn window_events(mut self, window_events: WindowEventsFn<Ms, Mdl>) -> Self {
         self.window_events = Some(window_events);
         self
     }
@@ -492,6 +538,16 @@ impl<
     /// The sink function is a function which can update the model based
     /// on global messages. Consider to use a sink function when a
     /// submodule needs to trigger changes in other modules.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///fn sink(g_msg: GMsg, _model: &mut Model, _orders: &mut impl Orders<Msg, GMsg>) {
+    ///    match g_msg {
+    ///        GMsg::SayHello => log!("Hello!"),
+    ///    }
+    ///}
+    /// ```
     pub fn sink(mut self, sink: SinkFn<Ms, Mdl, ElC, GMs>) -> Self {
         self.sink = Some(sink);
         self
@@ -506,7 +562,7 @@ impl<
         InitAPIType: InitAPI<Ms, Mdl, ElC, GMs, Builder = Self>,
     > Builder<Ms, Mdl, ElC, GMs, InitAPIType>
 {
-    /// Build and run the app.
+    /// Build, mount and start the app.
     pub fn build_and_start(self) -> App<Ms, Mdl, ElC, GMs> {
         InitAPIType::build(self).run()
     }

src/vdom/builder/after_mount.rs

@@ -30,23 +30,17 @@ pub struct AfterMount<Mdl> {
 }
 
 impl<Mdl> AfterMount<Mdl> {
+    /// Creates a new `AfterMount` instance. You can also use `AfterMount::default`
+    /// if your `Model` implements `Default`.
     pub fn new(model: Mdl) -> Self {
         Self {
             model,
             url_handling: UrlHandling::default(),
         }
     }
 
-    // TODO: Change to const fn when possible.
-    // TODO: Relevant issue: https://github.com/rust-lang/rust/issues/60964
-    #[allow(clippy::missing_const_for_fn)]
-    pub fn model<NewMdl>(self, model: NewMdl) -> AfterMount<NewMdl> {
-        AfterMount {
-            model,
-            url_handling: self.url_handling,
-        }
-    }
-
+    /// - `UrlHandling::PassToRoutes` - your function `routes` will be called with initial URL. _[Default]_
+    /// - `UrlHandling::None` - URL won't be handled by Seed.
     pub const fn url_handling(mut self, url_handling: UrlHandling) -> Self {
         self.url_handling = url_handling;
         self

src/vdom/builder/before_mount.rs

@@ -61,21 +61,40 @@ impl Default for MountType {
 
 pub struct BeforeMount {
     pub(crate) mount_point_getter: Box<dyn FnOnce() -> Element>,
-    /// How to handle elements already present in the mount. Defaults to [`MountType::Append`]
-    /// in the constructors.
+    /// How to handle elements already present in the mount.
+    /// Defaults to `MountType::Append` in the constructors.
     pub(crate) mount_type: MountType,
 }
 
 impl BeforeMount {
+    /// Creates a new `BeforeMount` instance. It's the alias for `BeforeMount::default`.
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Choose the element where the application will be mounted.
+    /// The default one is the element with `id` = "app".
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// // argument is `&str`
+    /// mount_point("another_id")
+    ///
+    /// // argument is `HTMLElement`
+    /// // NOTE: Be careful with mounting into body,
+    /// // it can cause hard-to-debug bugs when there are other scripts in the body.
+    /// mount_point(seed::body())
+    ///
+    /// // argument is `Element`
+    /// mount_point(seed::body().querySelector("section").unwrap().unwrap())
+    /// ```
     pub fn mount_point(mut self, mount_point: impl MountPoint + 'static) -> BeforeMount {
         self.mount_point_getter = Box::new(mount_point.element_getter());
         self
     }
 
+    /// How to handle elements already present in the mount point. Defaults to `MountType::Append`.
     pub const fn mount_type(mut self, mount_type: MountType) -> Self {
         self.mount_type = mount_type;
         self