docs: 📝 added crate docs for perseus package

packages/perseus/src/config_manager.rs

@@ -36,12 +36,14 @@ pub trait ConfigManager: Clone {
     async fn write(&self, name: &str, content: &str) -> Result<()>;
 }
 
+/// The default config 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).
 #[derive(Clone)]
 pub struct FsConfigManager {
     root_path: String,
 }
 impl FsConfigManager {
-    /// Creates a new filesystem configuration manager. This function only exists to preserve the API surface of the trait.
+    /// Creates a new filesystem configuration manager. You should provide a path like `/dist` here.
     pub fn new(root_path: String) -> Self {
         Self { root_path }
     }

packages/perseus/src/lib.rs

@@ -1,10 +1,44 @@
+/*!
+ * Perseus is a blazingly fast frontend web development framework built in Rust with support for major rendering strategies,
+ * reactivity without a virtual DOM, and extreme customizability. It wraps the lower-level capabilities of[Sycamore](https://github.com/sycamore-rs/sycamore)
+ * and provides a NextJS-like API!
+ *
+ * - ✨ Supports static generation (serving only static resources)
+ * - ✨ Supports server-side rendering (serving dynamic resources)
+ * - ✨ Supports revalidation after time and/or with custom logic (updating rendered pages)
+ * - ✨ Supports incremental regeneration (build on demand)
+ * - ✨ Open build matrix (use any rendering strategy with anything else, mostly)
+ * - ✨ CLI harness that lets you build apps with ease and confidence
+ *
+ * This is the documentation for the core Perseus crate, but there's also [a CLI](https://arctic-hen7.github.io/perseus/cli.html) and
+ * [integrations](https://arctic-hen7.github.io/perseus/serving.html) to make serving apps easier!
+ *
+ * # Resources
+ *
+ * These docs will help you as a reference, but [the book](https://arctic-hen7.github.io/perseus) should be your first port of call for
+ * learning about how to use Perseus and how it works.
+ *
+ * - [The Book](https://arctic-hen7.github.io/perseus)
+ * - [GitHub repository](https://github.com/arctic-hen7/perseus)
+ * - [Crate page](https://crates.io/crates/perseus)
+ * - [Gitter chat](https://gitter.im/perseus-framework/community)
+ * - [Discord server channel](https://discord.com/channels/820400041332179004/883168134331256892) (for Sycamore-related stuff)
+ */
+
+#![deny(missing_docs)]
+
+/// Utilities for building your app.
 pub mod build;
+/// Utilities for creating custom config managers, as well as the default `FsConfigManager`.
 pub mod config_manager;
-pub mod decode_time_str;
+mod decode_time_str;
 pub mod errors;
 mod macros;
+/// Utilities for serving your app. These are platform-agnostic, and you probably want an integration like [perseus-actix-web](https://crates.io/crates/perseus-actix-web).
 pub mod serve;
+/// Utilities to do with the app shell. You probably don't want to delve into here.
 pub mod shell;
+/// Utilities to do with templating. This is where the bulk of designing apps lies.
 pub mod template;
 
 pub use http;
@@ -16,7 +50,6 @@ pub use sycamore_router::Route;
 
 pub use crate::build::{build_template, build_templates};
 pub use crate::config_manager::{ConfigManager, FsConfigManager};
-pub use crate::decode_time_str::decode_time_str;
 pub use crate::errors::{err_to_status_code, ErrorCause};
 pub use crate::serve::{get_page, get_render_cfg};
 pub use crate::shell::{app_shell, ErrorPages};

packages/perseus/src/shell.rs

@@ -66,9 +66,12 @@ impl ErrorPages {
             fallback,
         }
     }
+    /// Adds a new page for the given status code. If a page was already defined for the given code, it will be updated by the mechanics of
+    /// the internal `HashMap`.
     pub fn add_page(&mut self, status: u16, page: ErrorPageTemplate<DomNode>) {
         self.status_pages.insert(status, page);
     }
+    /// Renders the appropriate error page to the given DOM container.
     pub fn render_page(&self, url: &str, status: &u16, err: &str, container: &NodeRef<DomNode>) {
         // Check if we have an explicitly defined page for this status code
         // If not, we'll render the fallback page

packages/perseus/src/template.rs

@@ -12,10 +12,13 @@ use sycamore::prelude::{GenericNode, Template as SycamoreTemplate};
 /// of what did what (rather than blindly working on a vector).
 #[derive(Default)]
 pub struct States {
+    /// Any state generated by the *build state* strategy.
     pub build_state: Option<String>,
+    /// Any state generated by the *request state* strategy.
     pub request_state: Option<String>,
 }
 impl States {
+    /// Creates a new instance of the states, setting both to `None`.
     pub fn new() -> Self {
         Self::default()
     }
@@ -52,7 +55,9 @@ type AsyncFnReturn<T> = Pin<Box<dyn Future<Output = T>>>;
 /// types are stabilized (https://github.com/rust-lang/rust/issues/29625https://github.com/rust-lang/rust/issues/29625).
 macro_rules! make_async_trait {
     ($name:ident, $return_ty:ty$(, $arg_name:ident: $arg:ty)*) => {
-        pub trait $name{
+        // These traits should be purely internal, the user is likely to shoot themselves in the foot
+        #[doc(hidden)]
+        pub trait $name {
             fn call(
                 &self,
                 // Each given argument is repeated
@@ -103,11 +108,18 @@ make_async_trait!(
 make_async_trait!(ShouldRevalidateFnType, StringResultWithCause<bool>);
 
 // A series of closure types that should not be typed out more than once
+/// The type of functions that are given a state and render a page. If you've defined state for your page, it's safe to `.unwrap()` the
+/// given `Option`.
 pub type TemplateFn<G> = Arc<dyn Fn(Option<String>) -> SycamoreTemplate<G>>;
+/// The type of functions that get build paths.
 pub type GetBuildPathsFn = Arc<dyn GetBuildPathsFnType>;
+/// The type of functions that get build state.
 pub type GetBuildStateFn = Arc<dyn GetBuildStateFnType>;
+/// The type of functions that get request state.
 pub type GetRequestStateFn = Arc<dyn GetRequestStateFnType>;
+/// The type of functions that check if a template sghould revalidate.
 pub type ShouldRevalidateFn = Arc<dyn ShouldRevalidateFnType>;
+/// The type of functions that amalgamate build and request states.
 pub type AmalgamateStatesFn = Arc<dyn Fn(States) -> StringResultWithCause<Option<String>>>;
 
 /// This allows the specification of all the template templates in an app and how to render them. If no rendering logic is provided at all,
@@ -285,6 +297,7 @@ impl<G: GenericNode> Template<G> {
     pub fn get_path(&self) -> String {
         self.path.clone()
     }
+    /// Gets the interval after which the template will next revalidate.
     pub fn get_revalidate_interval(&self) -> Option<String> {
         self.revalidate_after.clone()
     }
@@ -332,34 +345,43 @@ impl<G: GenericNode> Template<G> {
     }
 
     // Builder setters
+    /// Sets the template rendering function to use.
     pub fn template(mut self, val: TemplateFn<G>) -> Template<G> {
         self.template = val;
         self
     }
+    /// Enables the *build paths* strategy with the given function.
     pub fn build_paths_fn(mut self, val: GetBuildPathsFn) -> Template<G> {
         self.get_build_paths = Some(val);
         self
     }
+    /// Enables the *incremental generation* strategy with the given function.
     pub fn incremental_path_rendering(mut self, val: bool) -> Template<G> {
         self.incremental_path_rendering = val;
         self
     }
+    /// Enables the *build state* strategy with the given function.
     pub fn build_state_fn(mut self, val: GetBuildStateFn) -> Template<G> {
         self.get_build_state = Some(val);
         self
     }
+    /// Enables the *request state* strategy with the given function.
     pub fn request_state_fn(mut self, val: GetRequestStateFn) -> Template<G> {
         self.get_request_state = Some(val);
         self
     }
+    /// Enables the *revalidation* strategy (logic variant) with the given function.
     pub fn should_revalidate_fn(mut self, val: ShouldRevalidateFn) -> Template<G> {
         self.should_revalidate = Some(val);
         self
     }
+    /// Enables the *revalidation* strategy (time variant). This takes a time string of a form like `1w` for one week. More details are available
+    /// [in the book](https://arctic-hen7.github.io/perseus/strategies/revalidation.html#time-syntax).
     pub fn revalidate_after(mut self, val: String) -> Template<G> {
         self.revalidate_after = Some(val);
         self
     }
+    /// Enables state amalgamation with the given function.
     pub fn amalgamate_states_fn(mut self, val: AmalgamateStatesFn) -> Template<G> {
         self.amalgamate_states = Some(val);
         self