docs: finished updates to code-level docs

There may be some missing links or other issues here, but those can be
sorted out through user reporting. The API docs should be far more
complete now!

packages/perseus/src/engine/build.rs

@@ -9,8 +9,8 @@ use crate::{
 use std::rc::Rc;
 
 /// Builds the app, calling all necessary plugin opportunities. This works
-/// solely with the properties provided in the given `PerseusApp`, so this is
-/// entirely engine-agnostic.
+/// solely with the properties provided in the given
+/// [`PerseusApp`](crate::PerseusApp), so this is entirely engine-agnostic.
 ///
 /// Note that this expects to be run in the root of the project.
 pub async fn build<M: MutableStore, T: TranslationsManager>(

packages/perseus/src/engine/export.rs

@@ -15,10 +15,10 @@ use std::rc::Rc;
 use crate::errors::*;
 use crate::{i18n::TranslationsManager, stores::MutableStore, PerseusAppBase};
 
-/// Exports the app to static files, given a `PerseusApp`. This is
+/// Exports the app to static files, given a [`PerseusApp`]. This is
 /// engine-agnostic, using the `exported` subfolder in the immutable store as a
 /// destination directory. By default this will end up at `dist/exported/`
-/// (customizable through `PerseusApp`).
+/// (customizable through [`PerseusApp`]).
 ///
 /// Note that this expects to be run in the root of the project.
 pub async fn export<M: MutableStore, T: TranslationsManager>(

packages/perseus/src/engine/get_op.rs

@@ -2,6 +2,11 @@ use std::env;
 
 /// Determines the engine operation to be performed by examining environment
 /// variables (set automatically by the CLI as appropriate).
+///
+/// *Note:* in production, it would be inconvenient to provide an environment
+/// variable just to get the server to work, so release builds run the server
+/// by default if the relevant environment variable is unset. If the same
+/// situation occurs in development however, `None` will be returned.
 pub fn get_op() -> Option<EngineOperation> {
     let var = match env::var("PERSEUS_ENGINE_OPERATION").ok() {
         Some(var) => var,

packages/perseus/src/engine/serve.rs

@@ -9,15 +9,6 @@ use std::fs;
 use std::sync::Arc;
 use sycamore::web::SsrNode;
 
-// TODO Can we unify the two modes of server execution now?
-// This server executable can be run in two modes:
-//      dev: at the root of the project, works with that file structure
-//      prod: as a standalone executable with a `dist/` directory as a sibling
-// (also present with the dev file structure)
-
-// Note: the default servers for integrations are now stored in the crates of
-// those integrations
-
 /// Gets the host and port to serve on based on environment variables, which are
 /// universally used for configuration regardless of engine.
 pub(crate) fn get_host_and_port() -> (String, u16) {

packages/perseus/src/errors.rs

@@ -256,12 +256,12 @@ impl<E: std::error::Error + Send + Sync + 'static> From<E> for GenericErrorWithC
 }
 
 /// Creates a new [`GenericErrorWithCause` (the error type behind
-/// [`RenderFnResultWithCause`]) efficiently. This allows you to explicitly
-/// return errors from any state-generation functions, including both an error
-/// and a statement of whether the server or the client is responsible. With
-/// this macro, you can use any of the following syntaxes (substituting
-/// `"error!"` for any error that can be converted with `.into()` into a
-/// `Box<dyn std::error::Error>`):
+/// [`RenderFnResultWithCause`](crate::RenderFnResultWithCause)) efficiently.
+/// This allows you to explicitly return errors from any state-generation
+/// functions, including both an error and a statement of whether the server or
+/// the client is responsible. With this macro, you can use any of the following
+/// syntaxes (substituting `"error!"` for any error that can be converted with
+/// `.into()` into a `Box<dyn std::error::Error>`):
 ///
 /// - `blame_err!(client, "error!")` -- an error that's the client's fault, with
 ///   the default HTTP status code (400, a generic client error)

packages/perseus/src/i18n/translations_manager.rs

@@ -85,14 +85,17 @@ async fn get_translations_str_and_cache(
 }
 
 /// The default translations manager. This will store static files in the
-/// specified location on disk. This should be suitable for nearly all
-/// development and serverful use-cases. Serverless is another matter though
-/// (more development needs to be done). This mandates that translations be
-/// stored as files named as the locale they describe (e.g. 'en-US.ftl',
-/// 'en-US.json', etc.).
+/// specified location on disk, which should be suitable for the majority
+/// of use-cases, though users who want to store translations somewhere
+/// other than on the filesystem should use an alternative implementation.
+/// This mandates that translations be stored as files named as the locale they
+/// describe (e.g. 'en-US.ftl', 'en-US.json', etc.).
 ///
 /// As this is used as the default translations manager by most apps, this also
-/// supports not using i18n at all.
+/// supports not using i18n at all (a dummy translations manager).
+///
+/// Note that this will cache translations upon initialization, meaning
+/// source files cannot be updated while the system is running.
 #[derive(Clone, Debug)]
 pub struct FsTranslationsManager {
     #[cfg(not(target_arch = "wasm32"))]
@@ -118,7 +121,7 @@ pub struct FsTranslationsManager {
 #[cfg(not(target_arch = "wasm32"))]
 impl FsTranslationsManager {
     /// Creates a new filesystem translations manager. You should provide a path
-    /// like `/translations` here. You should also provide the locales you
+    /// like `translations/` here. You should also provide the locales you
     /// want to cache, which will have their translations stored in memory. Any
     /// supported locales not specified here will not be cached, and must
     /// have their translations read from disk on every request. If fetching

packages/perseus/src/lib.rs

@@ -23,29 +23,34 @@ documentation, and this should mostly be used as a secondary reference source. Y
 #![forbid(unsafe_code)]
 #![recursion_limit = "256"] // TODO Do we need this anymore?
 
-/// TODO
+/// Utilities for working with the engine-side, particularly with regards to
+/// setting up the entrypoint for your app's build/export/server processes.
 #[cfg(not(target_arch = "wasm32"))]
 pub mod engine;
-/// TODO
+/// Utilities surrounding [`ErrorPages`] and their management.
 pub mod error_pages;
 pub mod errors;
-/// TODO
+/// Utilities for internationalization, the process of making your app available
+/// in multiple languages.
 pub mod i18n;
 /// Utilities for working with plugins.
 pub mod plugins;
-/// TODO
+/// Utilities for working with the router. Note that you should only have to use
+/// these when waiting for a page transition in normal use-cases.
 pub mod router;
-/// TODO
+/// Utilities for working with the server. These are fairly low-level, and
+/// are intended for use by those developing new server integrations.
 #[cfg(not(target_arch = "wasm32"))]
 pub mod server;
 /// Utilities for working with Perseus' state platform.
 pub mod state;
-/// Utilities for working with immutable and mutable stores. You can learn more
-/// about these in the book.
+/// Utilities for working with immutable and mutable stores. See
+/// [`ImmutableStore`] and [`MutableStore`] for details.
 pub mod stores;
-/// TODO
+/// Utilities for working with templates and state generation. This is by far
+/// the module you'll procably access the most.
 pub mod template;
-/// TODO
+/// General utilities that may be useful while building Perseus apps.
 pub mod utils;
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -111,5 +116,3 @@ pub mod log {
     pub use wasm_bindgen::JsValue;
     pub use web_sys::console::log_1 as log_js_value;
 }
-
-// TODO Fix feature flags

packages/perseus/src/plugins/plugins_list.rs

@@ -5,9 +5,11 @@ use std::collections::HashMap;
 
 type PluginDataMap = HashMap<String, Box<dyn Any + Send>>;
 
-/// A representation of all the plugins used by an app. Due to the sheer number
-/// and compexity of nested fields, this is best transferred in an `Rc`, which
-/// unfortunately results in double indirection for runner functions.
+/// A representation of all the plugins used by an app.
+///
+/// Due to the sheer number and compexity of nested fields, this is best
+/// transferred in an `Rc`, which unfortunately results in double indirection
+/// for runner functions.
 pub struct Plugins<G: Html> {
     /// The functional actions that this plugin takes. This is defined by
     /// default such that all actions are assigned to a default, and so they

packages/perseus/src/router/match_route.rs

@@ -54,7 +54,7 @@ macro_rules! get_template_for_path {
 }
 
 /// Determines the template to use for the given path by checking against the
-/// render configuration., also returning whether we matched a simple page or an
+/// render configuration, also returning whether we matched a simple page or an
 /// incrementally-generated one (`true` for incrementally generated). Note that
 /// simple pages include those on incrementally-generated templates that we
 /// pre-rendered with *build paths* at build-time (and are hence in an immutable
@@ -65,6 +65,9 @@ macro_rules! get_template_for_path {
 /// ISR, and we can infer about them based on template root path domains. If
 /// that domain system is violated, this routing algorithm will not behave as
 /// expected whatsoever (as far as routing goes, it's undefined behavior)!
+///
+/// *Note:* in the vast majority of cases, you should never need to use
+/// this function.
 pub fn get_template_for_path<G: Html>(
     raw_path: &str,
     render_cfg: &HashMap<String, String>,
@@ -86,6 +89,9 @@ pub fn get_template_for_path<G: Html>(
 /// Warning: this returns a `&Template<G>` rather than a `Rc<Template<G>>`, and
 /// thus should only be used independently of the rest of Perseus (through
 /// `match_route_atomic`).
+///
+/// *Note:* in the vast majority of cases, you should never need to use
+/// this function.
 pub fn get_template_for_path_atomic<'a, G: Html>(
     raw_path: &str,
     render_cfg: &HashMap<String, String>,
@@ -107,6 +113,9 @@ pub fn get_template_for_path_atomic<'a, G: Html>(
 /// i18n is being used. The path this takes should be raw, it may or may not
 /// have a locale, but should be split into segments by `/`, with empty ones
 /// having been removed.
+///
+/// *Note:* in the vast majority of cases, you should never need to use
+/// this function.
 pub fn match_route<G: Html>(
     path_slice: &[&str],
     render_cfg: &HashMap<String, String>,
@@ -173,6 +182,9 @@ pub fn match_route<G: Html>(
 
 /// A version of `match_route` that accepts an `ArcTemplateMap<G>`. This should
 /// be used in multithreaded situations, like on the server.
+///
+/// *Note:* in the vast majority of cases, you should never need to use
+/// this function.
 pub fn match_route_atomic<'a, G: Html>(
     path_slice: &[&str],
     render_cfg: &HashMap<String, String>,

packages/perseus/src/router/route_verdict.rs

@@ -21,10 +21,7 @@ pub struct RouteInfo<G: Html> {
     pub locale: String,
 }
 
-/// The possible outcomes of matching a route. This is an alternative
-/// implementation of Sycamore's `Route` trait to enable greater control and
-/// tighter integration of routing with templates. This can only be used if
-/// `Routes` has been defined in context (done automatically by the CLI).
+/// The possible outcomes of matching a route in an app.
 #[derive(Debug, Clone)]
 pub enum RouteVerdict<G: Html> {
     /// The given route was found, and route information is attached.

packages/perseus/src/router/router_state.rs

@@ -15,8 +15,9 @@ pub struct RouterState {
     /// the current page without losing context etc.
     last_verdict: Rc<RefCell<Option<RouteVerdict<TemplateNodeType>>>>,
     /// A flip-flop `RcSignal`. Whenever this is changed, the router will reload
-    /// the current page in the SPA style. As a user, you should rarely ever
-    /// need to do this, but it's used internally in the thawing process.
+    /// the current page in the SPA style (maintaining state). As a user, you
+    /// should rarely ever need to do this, but it's used internally in the
+    /// thawing process.
     pub(crate) reload_commander: RcSignal<bool>,
 }
 impl Default for RouterState {

packages/perseus/src/server/build_error_page.rs

@@ -4,7 +4,7 @@ use crate::translator::Translator;
 use crate::SsrNode;
 use std::rc::Rc;
 
-/// Prepares an HTMl error page for the client, with injected markers for
+/// Prepares an HTML error page for the client, with injected markers for
 /// hydration. In the event of an error, this should be returned to the client
 /// (with the appropriate status code) to allow Perseus to hydrate and display
 /// the correct error page. Note that this is only for use in initial loads

packages/perseus/src/server/get_render_cfg.rs

@@ -3,6 +3,10 @@ use crate::stores::ImmutableStore;
 use std::collections::HashMap;
 
 /// Gets the configuration of how to render each page using an immutable store.
+///
+/// The render configuration is an internal build artifact stored somewhere like
+/// `dist/`, generated automatically by the build process. The server provides
+/// it automatically to the client to optimize routing.
 pub async fn get_render_cfg(
     immutable_store: &ImmutableStore,
 ) -> Result<HashMap<String, String>, ServerError> {

packages/perseus/src/server/render.rs

@@ -252,8 +252,8 @@ pub struct GetPageProps<'a, M: MutableStore, T: TranslationsManager> {
     pub translations_manager: &'a T,
 }
 
-/// Internal logic behind `get_page`. The only differences are that this takes a
-/// full template rather than just a template name, which can avoid an
+/// Internal logic behind [`get_page`]. The only differences are that this takes
+/// a full template rather than just a template name, which can avoid an
 /// unnecessary lookup if you already know the template in full (e.g. initial
 /// load server-side routing). Because this handles templates with potentially
 /// revalidation and incremental generation, it uses both mutable and immutable
@@ -492,7 +492,6 @@ pub async fn get_page_for_template<M: MutableStore, T: TranslationsManager>(
 /// SSG/SSR/etc., whatever is needed for that page. Note that HTML generated at
 /// request-time will **always** replace anything generated at build-time,
 /// incrementally, revalidated, etc.
-#[allow(clippy::too_many_arguments)]
 pub async fn get_page<M: MutableStore, T: TranslationsManager>(
     props: GetPageProps<'_, M, T>,
     template_name: &str,

packages/perseus/src/template/core.rs

@@ -40,7 +40,8 @@ pub type RenderFnResult<T> = std::result::Result<T, Box<dyn std::error::Error +
 /// `.into()` or `?`, which will blame the server for the error by default and
 /// return a *500 Internal Server Error* HTTP status code. Otherwise, you'll
 /// need to manually instantiate [`GenericErrorWithCause`] and return that as
-/// the error type. Alternatively, you could use [`blame_err!`].
+/// the error type. Alternatively, you could use
+/// [`blame_err!`](crate::blame_err).
 pub type RenderFnResultWithCause<T> = std::result::Result<T, GenericErrorWithCause>;
 
 // A series of asynchronous closure traits that prevent the user from having to

packages/perseus/src/translator/fluent.rs

@@ -8,10 +8,10 @@ use unic_langid::{LanguageIdentifier, LanguageIdentifierError};
 /// The file extension used by the Fluent translator, which expects FTL files.
 pub const FLUENT_TRANSLATOR_FILE_EXT: &str = "ftl";
 
-/// Manages translations on the client-side for a single locale using Mozilla's [Fluent](https://projectfluent.org/) syntax. This
-/// should generally be placed into an `Rc<T>` and referred to by every template
-/// in an app. You do NOT want to be cloning potentially thousands of
-/// translations!
+/// Manages translations on the client-side for a single locale using Mozilla's [Fluent](https://projectfluent.org/) syntax.
+/// This is safely `Clone`able, and is provided through Sycamore's context
+/// system to every template in your app automatically. Usually, you will
+/// use this only through the [`t!`] and [`link!`] macros.
 ///
 /// Fluent supports compound messages, with many variants, which can specified
 /// here using the form `[id].[variant]` in a translation ID, as a `.` is not

packages/perseus/src/translator/mod.rs

@@ -51,7 +51,8 @@ pub use DummyTranslator as Translator;
 pub use DUMMY_TRANSLATOR_FILE_EXT as TRANSLATOR_FILE_EXT;
 
 /// Translates the given ID conveniently, taking arguments for interpolation as
-/// required.
+/// required. The final argument to any call of this macro must be a Sycamore
+/// reactive scope provided to the relevant Perseus template.
 #[macro_export]
 macro_rules! t {
     // When there are no arguments to interpolate
@@ -71,6 +72,8 @@ macro_rules! t {
     }};
 }
 /// Gets the link to the given resource in internationalized form conveniently.
+/// The final argument to any call of this macro must be a Sycamore reactive
+/// scope provided to the relevant Perseus template.
 #[macro_export]
 macro_rules! link {
     ($url:expr, $cx:expr) => {