new: Add more schema descriptions, remove some titles. (#1337)

* Add more comments.

* Regen.

Cargo.toml

@@ -50,7 +50,7 @@ reqwest = { version = "0.11.24", default-features = false, features = [
 	"native-tls-vendored",
 ] }
 rustc-hash = "1.1.0"
-schematic = { version = "0.14.1", default-features = false, features = [
+schematic = { version = "0.14.2", default-features = false, features = [
 	"schema",
 ] }
 semver = "1.0.21"

nextgen/config/src/project/owners_config.rs

@@ -3,14 +3,17 @@ use rustc_hash::FxHashMap;
 use schematic::{Config, PathSegment, ValidateError};
 
 cacheable!(
+    /// A mapping of file paths and file globs to owners.
     #[derive(Clone, Config, Debug, PartialEq)]
     #[serde(
         untagged,
         expecting = "expected a list of paths, or a map of paths to owners"
     )]
     pub enum OwnersPaths {
+        /// A list of file paths. The owner is the `defaultOwner`.
         #[setting(default)]
         List(Vec<String>),
+        /// A mapping of file paths to owners.
         Map(FxHashMap<String, Vec<String>>),
     }
 );

nextgen/config/src/project/task_config.rs

@@ -79,12 +79,16 @@ derive_enum!(
 );
 
 cacheable!(
+    /// Configures a command to execute, and its arguments.
     #[derive(Clone, Config, Debug, Eq, PartialEq)]
     #[serde(untagged, expecting = "expected a string or a list of strings")]
     pub enum TaskArgs {
+        /// No value defined.
         #[setting(default, null)]
         None,
+        /// A command and arguments as a string. Will be parsed into a list.
         String(String),
+        /// A command and arguments as a list of individual values.
         List(Vec<String>),
     }
 );
@@ -118,14 +122,17 @@ impl TaskDependencyConfig {
 }
 
 cacheable!(
+    /// Configures another task that a task depends on.
     #[derive(Clone, Config, Debug, Eq, PartialEq)]
     #[serde(
         untagged,
         expecting = "expected a valid target or dependency config object"
     )]
     pub enum TaskDependency {
+        /// A task referenced by target.
         Target(Target),
 
+        /// A task referenced by target, with additional parameters to pass through.
         #[setting(nested)]
         Config(TaskDependencyConfig),
     }
@@ -158,7 +165,7 @@ cacheable!(
         #[setting(nested)]
         pub args: TaskArgs,
 
-        /// Other tasks that this task depends on, and must run to completion,
+        /// Other tasks that this task depends on, and must run to completion
         /// before this task is ran. Can depend on sibling tasks, or tasks in
         /// other projects, using targets.
         #[setting(nested, validate = validate_deps)]

nextgen/config/src/project/task_options_config.rs

@@ -26,8 +26,11 @@ fn validate_interactive<C>(
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
 #[serde(untagged, rename_all = "kebab-case")]
 pub enum TaskOptionAffectedFiles {
+    /// Passed as command line arguments.
     Args,
+    /// Passed as environment variables.
     Env,
+    /// Passed as command line arguments and environment variables.
     Enabled(bool),
 }
 
@@ -63,10 +66,12 @@ impl<'de> Deserialize<'de> for TaskOptionAffectedFiles {
 }
 
 derive_enum!(
-    /// The pattern in which a task is dependent on a .env file.
+    /// The pattern in which a task is dependent on a `.env` file.
     #[serde(untagged, expecting = "expected a boolean or a file system path")]
     pub enum TaskOptionEnvFile {
+        /// Uses an `.env` file in the project root.
         Enabled(bool),
+        /// Explicit path to an `.env` file.
         File(FilePath),
     }
 );

nextgen/config/src/project_config.rs

@@ -63,13 +63,17 @@ cacheable!(
 );
 
 cacheable!(
+    /// Expanded information about a project dependency.
     #[derive(Clone, Config, Debug, PartialEq)]
     #[serde(
         untagged,
         expecting = "expected a project name or dependency config object"
     )]
     pub enum ProjectDependsOn {
+        /// A project referenced by ID.
         String(Id),
+
+        /// A project referenced by ID, with additional parameters to pass through.
         #[setting(nested)]
         Object(DependencyConfig),
     }

nextgen/config/src/template_config.rs

@@ -9,6 +9,7 @@ use std::path::Path;
 
 macro_rules! var_setting {
     ($name:ident, $ty:ty) => {
+        /// Configuration for a template variable.
         #[derive(Clone, Config, Debug, Eq, PartialEq)]
         pub struct $name {
             /// The default value of the variable if none was provided.

nextgen/config/src/toolchain/bin_config.rs

@@ -1,6 +1,7 @@
 use schematic::Config;
 use serde::Serialize;
 
+/// Configures to a tool-specific binary to install.
 #[derive(Clone, Config, Debug, Eq, PartialEq, Serialize)]
 pub struct BinConfig {
     /// Name of the binary, with optional version separated by `@`.
@@ -16,10 +17,14 @@ pub struct BinConfig {
     pub name: Option<String>,
 }
 
+/// Configures to a tool-specific binary to install.
 #[derive(Clone, Config, Debug, Eq, PartialEq, Serialize)]
 #[serde(untagged, expecting = "expecting a bin name, or bin config object")]
 pub enum BinEntry {
+    /// Name of a binary to install.
     Name(String),
+
+    /// Expanded configuration for a binary to install.
     #[setting(nested)]
     Config(BinConfig),
 }

nextgen/config/src/workspace/notifier_config.rs

@@ -3,6 +3,7 @@ use schematic::{validate, Config};
 /// Configures how and where notifications are sent.
 #[derive(Clone, Config, Debug)]
 pub struct NotifierConfig {
+    /// A secure URL in which to send webhooks to.
     #[setting(validate = validate::url_secure)]
     pub webhook_url: Option<String>,
 }

nextgen/config/src/workspace_config.rs

@@ -65,6 +65,7 @@ fn validate_projects<D, C>(
     Ok(())
 }
 
+/// Configures projects in the workspace, using both globs and explicit source paths.
 #[derive(Clone, Config, Debug)]
 pub struct WorkspaceProjectsConfig {
     /// A list of globs in which to locate project directories.
@@ -75,17 +76,21 @@ pub struct WorkspaceProjectsConfig {
     pub sources: FxHashMap<Id, String>,
 }
 
+/// Configures projects in the workspace.
 #[derive(Clone, Config, Debug)]
 #[config(serde(
     untagged,
     expecting = "expected a list of globs, a map of projects, or both"
 ))]
 pub enum WorkspaceProjects {
+    /// Using both globs and explicit source paths.
     #[setting(nested)]
     Both(WorkspaceProjectsConfig),
 
+    /// Using globs. Suffix with `moon.yml` to be distinct.
     Globs(Vec<String>),
 
+    /// Using a mapping of IDs to source paths.
     #[setting(default)]
     Sources(FxHashMap<Id, String>),
 }

packages/types/src/tasks-config.ts

@@ -134,7 +134,7 @@ export interface TaskConfig {
 	 */
 	command: TaskArgs;
 	/**
-	 * Other tasks that this task depends on, and must run to completion,
+	 * Other tasks that this task depends on, and must run to completion
 	 * before this task is ran. Can depend on sibling tasks, or tasks in
 	 * other projects, using targets.
 	 */
@@ -332,7 +332,7 @@ export interface PartialTaskConfig {
 	 */
 	command?: PartialTaskArgs | null;
 	/**
-	 * Other tasks that this task depends on, and must run to completion,
+	 * Other tasks that this task depends on, and must run to completion
 	 * before this task is ran. Can depend on sibling tasks, or tasks in
 	 * other projects, using targets.
 	 */

packages/types/src/template-config.ts

@@ -2,6 +2,7 @@
 
 /* eslint-disable */
 
+/** Configuration for a template variable. */
 export interface PartialTemplateVariableBoolSetting {
 	/** The default value of the variable if none was provided. */
 	default?: boolean | null;
@@ -33,6 +34,7 @@ export interface PartialTemplateVariableEnumSetting {
 	values?: PartialTemplateVariableEnumValue[] | null;
 }
 
+/** Configuration for a template variable. */
 export interface PartialTemplateVariableNumberSetting {
 	/** The default value of the variable if none was provided. */
 	default?: number | null;
@@ -43,6 +45,7 @@ export interface PartialTemplateVariableNumberSetting {
 	type?: 'number' | null;
 }
 
+/** Configuration for a template variable. */
 export interface PartialTemplateVariableStringSetting {
 	/** The default value of the variable if none was provided. */
 	default?: string | null;
@@ -93,6 +96,7 @@ export interface PartialTemplateFrontmatterConfig {
 	to?: string | null;
 }
 
+/** Configuration for a template variable. */
 export interface TemplateVariableBoolSetting {
 	/** The default value of the variable if none was provided. */
 	default: boolean;
@@ -124,6 +128,7 @@ export interface TemplateVariableEnumSetting {
 	values: TemplateVariableEnumValue[];
 }
 
+/** Configuration for a template variable. */
 export interface TemplateVariableNumberSetting {
 	/** The default value of the variable if none was provided. */
 	default: number;
@@ -134,6 +139,7 @@ export interface TemplateVariableNumberSetting {
 	type: 'number';
 }
 
+/** Configuration for a template variable. */
 export interface TemplateVariableStringSetting {
 	/** The default value of the variable if none was provided. */
 	default: string;

packages/types/src/toolchain-config.ts

@@ -49,6 +49,7 @@ export interface BunConfig {
 	version: string | null;
 }
 
+/** Configures to a tool-specific binary to install. */
 export interface BinConfig {
 	/** Name of the binary, with optional version separated by `@`. */
 	bin: string;
@@ -362,6 +363,7 @@ export interface PartialBunConfig {
 	version?: string | null;
 }
 
+/** Configures to a tool-specific binary to install. */
 export interface PartialBinConfig {
 	/** Name of the binary, with optional version separated by `@`. */
 	bin?: string | null;

packages/types/src/workspace-config.ts

@@ -124,9 +124,11 @@ export interface HasherConfig {
 
 /** Configures how and where notifications are sent. */
 export interface NotifierConfig {
+	/** A secure URL in which to send webhooks to. */
 	webhookUrl: string | null;
 }
 
+/** Configures projects in the workspace, using both globs and explicit source paths. */
 export interface WorkspaceProjectsConfig {
 	/**
 	 * A list of globs in which to locate project directories.
@@ -357,9 +359,11 @@ export interface PartialHasherConfig {
 
 /** Configures how and where notifications are sent. */
 export interface PartialNotifierConfig {
+	/** A secure URL in which to send webhooks to. */
 	webhookUrl?: string | null;
 }
 
+/** Configures projects in the workspace, using both globs and explicit source paths. */
 export interface PartialWorkspaceProjectsConfig {
 	/**
 	 * A list of globs in which to locate project directories.