From 76ef81c5bc4f6b4055c93ae005247fb4766bb333 Mon Sep 17 00:00:00 2001 From: arctic_hen7 Date: Fri, 8 Jul 2022 19:55:40 +1000 Subject: [PATCH] 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 | 4 +-- packages/perseus/src/engine/export.rs | 4 +-- packages/perseus/src/engine/get_op.rs | 5 ++++ packages/perseus/src/engine/serve.rs | 9 ------- packages/perseus/src/errors.rs | 12 ++++----- .../perseus/src/i18n/translations_manager.rs | 17 +++++++------ packages/perseus/src/lib.rs | 25 +++++++++++-------- packages/perseus/src/plugins/plugins_list.rs | 8 +++--- packages/perseus/src/router/match_route.rs | 14 ++++++++++- packages/perseus/src/router/route_verdict.rs | 5 +--- packages/perseus/src/router/router_state.rs | 5 ++-- .../perseus/src/server/build_error_page.rs | 2 +- packages/perseus/src/server/get_render_cfg.rs | 4 +++ packages/perseus/src/server/render.rs | 5 ++-- packages/perseus/src/template/core.rs | 3 ++- packages/perseus/src/translator/fluent.rs | 8 +++--- packages/perseus/src/translator/mod.rs | 5 +++- 17 files changed, 78 insertions(+), 57 deletions(-) diff --git a/packages/perseus/src/engine/build.rs b/packages/perseus/src/engine/build.rs index 61fe37d3d8..96df035f6e 100644 --- a/packages/perseus/src/engine/build.rs +++ b/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( diff --git a/packages/perseus/src/engine/export.rs b/packages/perseus/src/engine/export.rs index 5a86b8503b..f68f135c3d 100644 --- a/packages/perseus/src/engine/export.rs +++ b/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( diff --git a/packages/perseus/src/engine/get_op.rs b/packages/perseus/src/engine/get_op.rs index 77b5f0e7d1..bd6cbefcb4 100644 --- a/packages/perseus/src/engine/get_op.rs +++ b/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 { let var = match env::var("PERSEUS_ENGINE_OPERATION").ok() { Some(var) => var, diff --git a/packages/perseus/src/engine/serve.rs b/packages/perseus/src/engine/serve.rs index 0f4022db53..f8c8e3b535 100644 --- a/packages/perseus/src/engine/serve.rs +++ b/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) { diff --git a/packages/perseus/src/errors.rs b/packages/perseus/src/errors.rs index ccd5a6afa7..c5d5d152be 100644 --- a/packages/perseus/src/errors.rs +++ b/packages/perseus/src/errors.rs @@ -256,12 +256,12 @@ impl From 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`): +/// [`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`): /// /// - `blame_err!(client, "error!")` -- an error that's the client's fault, with /// the default HTTP status code (400, a generic client error) diff --git a/packages/perseus/src/i18n/translations_manager.rs b/packages/perseus/src/i18n/translations_manager.rs index c3684dc94a..604ce4c5d8 100644 --- a/packages/perseus/src/i18n/translations_manager.rs +++ b/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 diff --git a/packages/perseus/src/lib.rs b/packages/perseus/src/lib.rs index 73f4790538..63c638f4cd 100644 --- a/packages/perseus/src/lib.rs +++ b/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 diff --git a/packages/perseus/src/plugins/plugins_list.rs b/packages/perseus/src/plugins/plugins_list.rs index 2a9b8e0c3f..22b8c7c4f9 100644 --- a/packages/perseus/src/plugins/plugins_list.rs +++ b/packages/perseus/src/plugins/plugins_list.rs @@ -5,9 +5,11 @@ use std::collections::HashMap; type PluginDataMap = HashMap>; -/// 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 { /// The functional actions that this plugin takes. This is defined by /// default such that all actions are assigned to a default, and so they diff --git a/packages/perseus/src/router/match_route.rs b/packages/perseus/src/router/match_route.rs index 74b6e69946..d7c19c8291 100644 --- a/packages/perseus/src/router/match_route.rs +++ b/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( raw_path: &str, render_cfg: &HashMap, @@ -86,6 +89,9 @@ pub fn get_template_for_path( /// Warning: this returns a `&Template` rather than a `Rc>`, 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, @@ -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( path_slice: &[&str], render_cfg: &HashMap, @@ -173,6 +182,9 @@ pub fn match_route( /// A version of `match_route` that accepts an `ArcTemplateMap`. 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, diff --git a/packages/perseus/src/router/route_verdict.rs b/packages/perseus/src/router/route_verdict.rs index 819f932b03..a19413cfc9 100644 --- a/packages/perseus/src/router/route_verdict.rs +++ b/packages/perseus/src/router/route_verdict.rs @@ -21,10 +21,7 @@ pub struct RouteInfo { 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 { /// The given route was found, and route information is attached. diff --git a/packages/perseus/src/router/router_state.rs b/packages/perseus/src/router/router_state.rs index 6ef0f64698..34a4022bf2 100644 --- a/packages/perseus/src/router/router_state.rs +++ b/packages/perseus/src/router/router_state.rs @@ -15,8 +15,9 @@ pub struct RouterState { /// the current page without losing context etc. last_verdict: Rc>>>, /// 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, } impl Default for RouterState { diff --git a/packages/perseus/src/server/build_error_page.rs b/packages/perseus/src/server/build_error_page.rs index 26412abfb9..d308fb1ed9 100644 --- a/packages/perseus/src/server/build_error_page.rs +++ b/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 diff --git a/packages/perseus/src/server/get_render_cfg.rs b/packages/perseus/src/server/get_render_cfg.rs index cf0492d8ef..19280da836 100644 --- a/packages/perseus/src/server/get_render_cfg.rs +++ b/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, ServerError> { diff --git a/packages/perseus/src/server/render.rs b/packages/perseus/src/server/render.rs index c52c7eec74..528aaa027c 100644 --- a/packages/perseus/src/server/render.rs +++ b/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( /// 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( props: GetPageProps<'_, M, T>, template_name: &str, diff --git a/packages/perseus/src/template/core.rs b/packages/perseus/src/template/core.rs index 83bf9490d7..72be407baa 100644 --- a/packages/perseus/src/template/core.rs +++ b/packages/perseus/src/template/core.rs @@ -40,7 +40,8 @@ pub type RenderFnResult = std::result::Result = std::result::Result; // A series of asynchronous closure traits that prevent the user from having to diff --git a/packages/perseus/src/translator/fluent.rs b/packages/perseus/src/translator/fluent.rs index 6cfc359213..101b825ffb 100644 --- a/packages/perseus/src/translator/fluent.rs +++ b/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` 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 diff --git a/packages/perseus/src/translator/mod.rs b/packages/perseus/src/translator/mod.rs index bf8f8e3e43..17da7521a5 100644 --- a/packages/perseus/src/translator/mod.rs +++ b/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) => {