Code docs

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.
 ///

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},

src/message_queue.rs

@@ -2,26 +2,6 @@ use std::sync::{Mutex, RwLock};
 
 use futures::sync::oneshot;
 
-struct Listener<T> {
-    sender: oneshot::Sender<(u32, Vec<T>)>,
-    cursor: u32,
-}
-
-fn fire_listener_if_ready<T: Clone>(
-    messages: &[T],
-    listener: Listener<T>,
-) -> Result<(), Listener<T>> {
-    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<T: Clone> MessageQueue<T> {
         self.messages.read().unwrap().len() as u32
     }
 }
+
+struct Listener<T> {
+    sender: oneshot::Sender<(u32, Vec<T>)>,
+    cursor: u32,
+}
+
+fn fire_listener_if_ready<T: Clone>(
+    messages: &[T],
+    listener: Listener<T>,
+) -> Result<(), Listener<T>> {
+    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)
+    }
+}

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 {

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

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,

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};

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 {

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,

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;

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};
 

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<T: Serialize>(
+    value: T,
+    code: StatusCode,
+) -> Box<dyn Future<Item = hyper::Response<hyper::Body>, 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<T: Serialize>(
+    value: T,
+) -> Box<dyn Future<Item = hyper::Response<hyper::Body>, Error = hyper::Error> + Send> {
+    json(value, StatusCode::OK)
+}
+
 fn response_json<T: Serialize>(value: T, code: StatusCode) -> Response<Body> {
     let serialized = match serde_json::to_string(&value) {
         Ok(v) => v,
@@ -20,16 +35,3 @@ fn response_json<T: Serialize>(value: T, code: StatusCode) -> Response<Body> {
         .body(Body::from(serialized))
         .unwrap()
 }
-
-pub fn json<T: Serialize>(
-    value: T,
-    code: StatusCode,
-) -> Box<dyn Future<Item = hyper::Response<hyper::Body>, Error = hyper::Error> + Send> {
-    Box::new(future::ok(response_json(value, code)))
-}
-
-pub fn json_ok<T: Serialize>(
-    value: T,
-) -> Box<dyn Future<Item = hyper::Response<hyper::Body>, Error = hyper::Error> + Send> {
-    json(value, StatusCode::OK)
-}