more docs

Author: noxware

moly-kit/src/lib.rs

@@ -1,3 +1,58 @@
+//! # Basic usage
+//!
+//! ## Installation
+//! Add MolyKit to your dependencies.
+//! ```toml
+//! moly-kit = { version = "*", features = ["full"] }
+//! ```
+//!
+//! ## DSL
+//! Import the batteries-included [Chat] widget.
+//! ```
+//! use moly_kit::widgets::chat::Chat;
+//! ```
+//! Then, add it somewhere in your parent widget.
+//! ```
+//! chat = <Chat> {}
+//! ```
+//!
+//! ## Rust
+//! We need to give the chat a [BotRepo], which allows [Chat] to pull information
+//! about the available bots and send messages to them.
+//!
+//! A [BotRepo] can be directly created from a [BotClient], which interacts
+//! with (mostly remote) bot providers like OpenAI, Ollama, OpenRouter,
+//! Moly Server, MoFa, etc.
+//!
+//! An OpenAI compatible client comes out-of-the-box with MolyKit, [MolyClient].
+//!
+//! So, add the following somewhere appropriate (like in `after_new_from_doc`
+//! from Makepad) to give [Chat] its [ChatRepo]:
+//! ```rust
+//! use moly_kit::*
+//!
+//! let mut client = MolyClient::new("https://api.openai.com".into());
+//! client.set_key("<YOUR_KEY>".into());
+//!
+//! let repo = BotRepo::from(client);
+//!
+//! self.chat(id!(chat)).write_with(|chat| {
+//!   chat.bot_repo = repo;
+//! })
+//! ```
+//!
+//! # Advanced usage
+//! [Chat] is by default a very automatic widget, but it exposes its lifecycle
+//! through a "hook" mechanism. This mechanism allows you to:
+//! - Know that something will happen.
+//! - Know that something already happened.
+//! - Abort something before it happens.
+//! - Replace that aborted thing with something else.
+//! - Inject tasks to be executed by the [Chat].
+//! - Change the payload of a task affecting the operation when executed.
+//!
+//! TODO: Continue writing.
+
 pub mod clients;
 pub mod protocol;
 pub mod utils;

moly-kit/src/widgets/chat.rs

@@ -1,5 +1,3 @@
-//! A batteries-included chat to to implement chatbots.
-
 use futures::{stream::AbortHandle, StreamExt};
 use makepad_widgets::*;
 use std::cell::{Ref, RefMut};
@@ -173,6 +171,7 @@ impl<'e> ChatHookWriter<'e> {
     }
 }
 
+/// A batteries-included chat to to implement chatbots.
 #[derive(Live, LiveHook, Widget)]
 pub struct Chat {
     #[deref]
@@ -490,6 +489,8 @@ fn chat_actions<'e>(
         .filter(move |a| a.widget_uid == widget_uid)
 }
 
+// TODO: Since `ChatRef` is generated by a macro, I can't document this to give
+// these functions better visibility from the module view.
 impl ChatRef {
     /// Immutable access to the underlying [Chat].
     ///

moly-kit/src/widgets/messages.rs

@@ -1,7 +1,3 @@
-//! View over a conversation with messages.
-//!
-//! This is mostly a dummy widget. Prefer using and adapting [crate::widgets::chat::Chat] instead.
-
 use std::cell::{Ref, RefMut};
 
 use crate::{
@@ -233,6 +229,9 @@ struct Editor {
     buffer: String,
 }
 
+/// View over a conversation with messages.
+///
+/// This is mostly a dummy widget. Prefer using and adapting [crate::widgets::chat::Chat] instead.
 #[derive(Live, LiveHook, Widget)]
 pub struct Messages {
     #[deref]

moly-kit/src/widgets/prompt_input.rs

@@ -1,7 +1,3 @@
-//! A prepared text input for conversation with bots.
-//!
-//! This is mostly a dummy widget. Prefer using and adapting [crate::widgets::chat::Chat] instead.
-
 use makepad_widgets::*;
 use std::cell::{Ref, RefMut};
 
@@ -98,6 +94,9 @@ pub enum Interactivity {
     Disabled,
 }
 
+/// A prepared text input for conversation with bots.
+///
+/// This is mostly a dummy widget. Prefer using and adapting [crate::widgets::chat::Chat] instead.
 #[derive(Live, LiveHook, Widget)]
 pub struct PromptInput {
     #[deref]