diff --git a/src/change_processor.rs b/src/change_processor.rs index a964c6ad..b7ad8b20 100644 --- a/src/change_processor.rs +++ b/src/change_processor.rs @@ -16,6 +16,9 @@ use crate::{ snapshot_middleware::{snapshot_from_vfs, snapshot_project_node}, }; +/// Processes file change events, updates the DOM, and sends those updates +/// through a channel for other stuff to consume. +/// /// Owns the connection between Rojo's VFS and its DOM by holding onto another /// thread that processes messages. /// diff --git a/src/lua_ast.rs b/src/lua_ast.rs index b29370b4..c31b609f 100644 --- a/src/lua_ast.rs +++ b/src/lua_ast.rs @@ -1,4 +1,5 @@ -//! Defines module for defining a small Lua AST for simple codegen. +//! Defines module for defining a small Lua AST for simple codegen. Rojo uses +//! this module to convert JSON into generated Lua code. use std::{ fmt::{self, Write}, diff --git a/src/message_queue.rs b/src/message_queue.rs index 8542c671..13c18ce4 100644 --- a/src/message_queue.rs +++ b/src/message_queue.rs @@ -2,26 +2,6 @@ use std::sync::{Mutex, RwLock}; use futures::sync::oneshot; -struct Listener { - sender: oneshot::Sender<(u32, Vec)>, - cursor: u32, -} - -fn fire_listener_if_ready( - messages: &[T], - listener: Listener, -) -> Result<(), Listener> { - let current_cursor = messages.len() as u32; - - if listener.cursor < current_cursor { - let new_messages = messages[(listener.cursor as usize)..].to_vec(); - let _ = listener.sender.send((current_cursor, new_messages)); - Ok(()) - } else { - Err(listener) - } -} - /// A message queue with persistent history that can be subscribed to. /// /// Definitely non-optimal. This would ideally be a lockless mpmc queue. @@ -97,3 +77,23 @@ impl MessageQueue { self.messages.read().unwrap().len() as u32 } } + +struct Listener { + sender: oneshot::Sender<(u32, Vec)>, + cursor: u32, +} + +fn fire_listener_if_ready( + messages: &[T], + listener: Listener, +) -> Result<(), Listener> { + let current_cursor = messages.len() as u32; + + if listener.cursor < current_cursor { + let new_messages = messages[(listener.cursor as usize)..].to_vec(); + let _ = listener.sender.send((current_cursor, new_messages)); + Ok(()) + } else { + Err(listener) + } +} diff --git a/src/resolution.rs b/src/resolution.rs index a72f454f..94b481b4 100644 --- a/src/resolution.rs +++ b/src/resolution.rs @@ -5,6 +5,12 @@ use rbx_dom_weak::types::{Color3, Content, Enum, Variant, VariantType, Vector2, use rbx_reflection::{DataType, PropertyDescriptor}; use serde::{Deserialize, Serialize}; +/// A user-friendly version of `Variant` that supports specifying ambiguous +/// values. Ambiguous values need a reflection database to be resolved to a +/// usable value. +/// +/// This type is used in Rojo projects and JSON models to make specifying the +/// most common types of properties, like strings or vectors, much easier. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(untagged)] pub enum UnresolvedValue { diff --git a/src/serve_session.rs b/src/serve_session.rs index 575bc54b..13b8037c 100644 --- a/src/serve_session.rs +++ b/src/serve_session.rs @@ -24,7 +24,9 @@ use crate::{ snapshot_middleware::snapshot_from_vfs, }; -/// Contains all of the state for a Rojo serve session. +/// Contains all of the state for a Rojo serve session. A serve session is used +/// when we need to build a Rojo tree and possibly rebuild it when input files +/// change. /// /// Nothing here is specific to any Rojo interface. Though the primary way to /// interact with a serve session is Rojo's HTTP right now, there's no reason diff --git a/src/snapshot_middleware/mod.rs b/src/snapshot_middleware/mod.rs index bf9f4e8c..b6bbb432 100644 --- a/src/snapshot_middleware/mod.rs +++ b/src/snapshot_middleware/mod.rs @@ -1,5 +1,7 @@ //! Defines the semantics that Rojo uses to turn entries on the filesystem into //! Roblox instances using the instance snapshot subsystem. +//! +//! These modules define how files turn into instances. #![allow(dead_code)] @@ -38,6 +40,8 @@ use self::{ pub use self::project::snapshot_project_node; +/// The main entrypoint to the snapshot function. This function can be pointed +/// at any path and will return something if Rojo knows how to deal with it. pub fn snapshot_from_vfs( context: &InstanceContext, vfs: &Vfs, diff --git a/src/tree_view.rs b/src/tree_view.rs index db0624d4..f6f05ad6 100644 --- a/src/tree_view.rs +++ b/src/tree_view.rs @@ -1,3 +1,6 @@ +//! Utiilty that helps redact nondeterministic information from trees so that +//! they can be part of snapshot tests. + use std::collections::HashMap; use rbx_dom_weak::types::{Ref, Variant}; diff --git a/src/web/assets.rs b/src/web/assets.rs index 09bfc3db..37adbe13 100644 --- a/src/web/assets.rs +++ b/src/web/assets.rs @@ -1,3 +1,7 @@ +//! A simple asset reloading system intended for iterating on CSS. When in the +//! `dev_live_assets` feature is enabled, files are read from disk and watched +//! for changes. Otherwise, they're baked into the executable. + macro_rules! declare_asset { ($name: ident, $path: expr) => { pub fn $name() -> &'static str { diff --git a/src/web/interface.rs b/src/web/interface.rs index 403592ea..f5bda237 100644 --- a/src/web/interface.rs +++ b/src/web/interface.rs @@ -1,4 +1,6 @@ -//! Defines all the structs needed to interact with the Rojo Serve API. +//! Defines all the structs needed to interact with the Rojo Serve API. This is +//! useful for tests to be able to use the same data structures as the +//! implementation. use std::{ borrow::Cow, diff --git a/src/web/mod.rs b/src/web/mod.rs index 512532ca..5b3109f8 100644 --- a/src/web/mod.rs +++ b/src/web/mod.rs @@ -1,3 +1,7 @@ +//! Defines the Rojo web interface. This is what the Roblox Studio plugin +//! communicates with. Eventually, we'll make this API stable, produce better +//! documentation for it, and open it up for other consumers. + mod api; mod assets; pub mod interface; diff --git a/src/web/ui.rs b/src/web/ui.rs index 7cc58d77..6ace230c 100644 --- a/src/web/ui.rs +++ b/src/web/ui.rs @@ -1,4 +1,8 @@ -//! Defines the HTTP-based UI. These endpoints generally return HTML and SVG. +//! Defines the HTTP-based Rojo UI. It uses ritz for templating, which is like +//! JSX for Rust. Eventually we should probably replace this with a new +//! framework, maybe using JS and client side rendering. +//! +//! These endpoints generally return HTML and SVG. use std::{borrow::Cow, sync::Arc, time::Duration}; diff --git a/src/web/util.rs b/src/web/util.rs index b882b372..26ddec61 100644 --- a/src/web/util.rs +++ b/src/web/util.rs @@ -2,6 +2,21 @@ use futures::{future, Future}; use hyper::{header::CONTENT_TYPE, Body, Response, StatusCode}; use serde::Serialize; +/// Respond to a request with JSON and the given status code. +pub fn json( + value: T, + code: StatusCode, +) -> Box, Error = hyper::Error> + Send> { + Box::new(future::ok(response_json(value, code))) +} + +/// Respond to a request with a 200 OK response containing JSON. +pub fn json_ok( + value: T, +) -> Box, Error = hyper::Error> + Send> { + json(value, StatusCode::OK) +} + fn response_json(value: T, code: StatusCode) -> Response { let serialized = match serde_json::to_string(&value) { Ok(v) => v, @@ -20,16 +35,3 @@ fn response_json(value: T, code: StatusCode) -> Response { .body(Body::from(serialized)) .unwrap() } - -pub fn json( - value: T, - code: StatusCode, -) -> Box, Error = hyper::Error> + Send> { - Box::new(future::ok(response_json(value, code))) -} - -pub fn json_ok( - value: T, -) -> Box, Error = hyper::Error> + Send> { - json(value, StatusCode::OK) -}