Unverified Commit c1156571 authored by Benjamin Woodruff ‮'s avatar Benjamin Woodruff Committed by GitHub

Turbopack: Deduplicate project options documentation (#98465)

By documenting both the partial and non-partial versions of these
objects, we were documenting everything multiple times.

Just reference the non-partial object from the partial object's
documentation.
parent e674165f
...@@ -289,13 +289,18 @@ impl DebugBuildPathsRouteKeys { ...@@ -289,13 +289,18 @@ impl DebugBuildPathsRouteKeys {
)] )]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
pub struct ProjectOptions { pub struct ProjectOptions {
/// An absolute root path (Unix or Windows path) from which all files must be nested under. /// An [canonicalized][std::fs::canonicalize] root path (Unix or Windows path) from which all
/// Trying to access a file outside this root will fail, so think of this as a chroot. /// files must be nested under. Trying to access a file outside this root will fail, so think
/// E.g. `/home/user/projects/my-repo`. /// of this as a weak chroot. E.g. `/home/user/projects/my-repo`.
///
/// This serves two purposes:
/// - It gives us a root to configure the file system watcher with.
/// - It ensures the cache is portable when the root path is moved, since every other path is
/// relative to it.
pub root_path: RcStr, pub root_path: RcStr,
/// A path which contains the app/pages directories, relative to [`Project::project_path`], /// A path which contains the app/pages directories, relative to [`Project::project_path`].
/// always Unix path. E.g. `apps/my-app` /// Always a Unix-style (`/`-separated) path. E.g. `apps/my-app`.
pub project_path: RcStr, pub project_path: RcStr,
/// The contents of next.config.js, serialized to JSON. /// The contents of next.config.js, serialized to JSON.
...@@ -304,8 +309,7 @@ pub struct ProjectOptions { ...@@ -304,8 +309,7 @@ pub struct ProjectOptions {
/// A map of environment variables to use when compiling code. /// A map of environment variables to use when compiling code.
pub env: Vec<(RcStr, RcStr)>, pub env: Vec<(RcStr, RcStr)>,
/// A map of environment variables which should get injected at compile /// A map of environment variables which should get injected at compile time.
/// time.
pub define_env: DefineEnv, pub define_env: DefineEnv,
/// Filesystem watcher options. /// Filesystem watcher options.
...@@ -326,9 +330,8 @@ pub struct ProjectOptions { ...@@ -326,9 +330,8 @@ pub struct ProjectOptions {
/// The browserslist query to use for targeting browsers. /// The browserslist query to use for targeting browsers.
pub browserslist_query: RcStr, pub browserslist_query: RcStr,
/// When the code is minified, this opts out of the default mangling of /// When the code is minified, this opts out of the default mangling of local names for
/// local names for variables, functions etc., which can be useful for /// variables, functions etc., which can be useful for debugging/profiling purposes.
/// debugging/profiling purposes.
pub no_mangling: bool, pub no_mangling: bool,
/// Whether to write the route hashes manifest. /// Whether to write the route hashes manifest.
...@@ -337,8 +340,8 @@ pub struct ProjectOptions { ...@@ -337,8 +340,8 @@ pub struct ProjectOptions {
/// The version of Node.js that is available/currently running. /// The version of Node.js that is available/currently running.
pub current_node_js_version: RcStr, pub current_node_js_version: RcStr,
/// Debug build paths for selective builds. /// Debug build paths for selective builds. When set, only routes matching these paths will be
/// When set, only routes matching these paths will be included in the build. /// included in the build.
pub debug_build_paths: Option<DebugBuildPaths>, pub debug_build_paths: Option<DebugBuildPaths>,
/// App-router page routes that should be built after non-deferred routes. /// App-router page routes that should be built after non-deferred routes.
...@@ -350,57 +353,42 @@ pub struct ProjectOptions { ...@@ -350,57 +353,42 @@ pub struct ProjectOptions {
/// The version of Next.js that is running. /// The version of Next.js that is running.
pub next_version: RcStr, pub next_version: RcStr,
/// Whether server-side HMR is enabled (disabled with --no-server-fast-refresh). /// Whether server-side HMR is enabled (disabled with `--no-server-fast-refresh`).
pub server_hmr: bool, pub server_hmr: bool,
} }
/// The subset of [`ProjectOptions`] that may change without restarting the process. Used by
/// [`ProjectContainer::update`].
///
/// Refer to [`ProjectOptions`] for documentation on this struct's fields.
#[derive(Default)] #[derive(Default)]
pub struct PartialProjectOptions { pub struct PartialProjectOptions {
/// A root path from which all files must be nested under. Trying to access
/// a file outside this root will fail. Think of this as a chroot.
pub root_path: Option<RcStr>, pub root_path: Option<RcStr>,
/// A path inside the root_path which contains the app/pages directories.
pub project_path: Option<RcStr>, pub project_path: Option<RcStr>,
/// The contents of next.config.js, serialized to JSON.
pub next_config: Option<RcStr>, pub next_config: Option<RcStr>,
/// A map of environment variables to use when compiling code.
pub env: Option<Vec<(RcStr, RcStr)>>, pub env: Option<Vec<(RcStr, RcStr)>>,
/// A map of environment variables which should get injected at compile
/// time.
pub define_env: Option<DefineEnv>, pub define_env: Option<DefineEnv>,
/// Filesystem watcher options.
pub watch: Option<WatchOptions>, pub watch: Option<WatchOptions>,
/// The mode in which Next.js is running.
pub dev: Option<bool>, pub dev: Option<bool>,
/// The server actions encryption key.
pub encryption_key: Option<RcStr>, pub encryption_key: Option<RcStr>,
/// The build id.
pub build_id: Option<RcStr>, pub build_id: Option<RcStr>,
/// Options for draft mode.
pub preview_props: Option<DraftModeOptions>, pub preview_props: Option<DraftModeOptions>,
/// The browserslist query to use for targeting browsers.
pub browserslist_query: Option<RcStr>, pub browserslist_query: Option<RcStr>,
/// When the code is minified, this opts out of the default mangling of
/// local names for variables, functions etc., which can be useful for
/// debugging/profiling purposes.
pub no_mangling: Option<bool>, pub no_mangling: Option<bool>,
/// Whether to write the route hashes manifest.
pub write_routes_hashes_manifest: Option<bool>, pub write_routes_hashes_manifest: Option<bool>,
/// Debug build paths for selective builds.
/// When set, only routes matching these paths will be included in the build.
pub debug_build_paths: Option<DebugBuildPaths>, pub debug_build_paths: Option<DebugBuildPaths>,
} }
......
...@@ -220,53 +220,36 @@ pub struct NapiProjectOptions { ...@@ -220,53 +220,36 @@ pub struct NapiProjectOptions {
pub server_hmr: Option<bool>, pub server_hmr: Option<bool>,
} }
/// [NapiProjectOptions] with all fields optional. /// The subset of [`NapiProjectOptions`] that may change without restarting the process. Used by
/// [`project_update`].
///
/// Refer to [`NapiProjectOptions`] for documentation on this struct's fields.
#[napi(object)] #[napi(object)]
pub struct NapiPartialProjectOptions { pub struct NapiPartialProjectOptions {
/// An absolute root path (Unix or Windows path) from which all files must be nested under.
/// Trying to access a file outside this root will fail, so think of this as a chroot.
/// E.g. `/home/user/projects/my-repo`.
pub root_path: Option<RcStr>, pub root_path: Option<RcStr>,
/// A path which contains the app/pages directories, relative to [`Project::root_path`], always
/// a Unix path.
/// E.g. `apps/my-app`
pub project_path: Option<RcStr>, pub project_path: Option<RcStr>,
/// Filesystem watcher options.
pub watch: Option<NapiWatchOptions>, pub watch: Option<NapiWatchOptions>,
/// The contents of next.config.js, serialized to JSON.
pub next_config: Option<RcStr>, pub next_config: Option<RcStr>,
/// A map of environment variables to use when compiling code.
pub env: Option<Vec<NapiEnvVar>>, pub env: Option<Vec<NapiEnvVar>>,
/// A map of environment variables which should get injected at compile
/// time.
pub define_env: Option<NapiDefineEnv>, pub define_env: Option<NapiDefineEnv>,
/// The mode in which Next.js is running.
pub dev: Option<bool>, pub dev: Option<bool>,
/// The server actions encryption key.
pub encryption_key: Option<RcStr>, pub encryption_key: Option<RcStr>,
/// The build id.
pub build_id: Option<RcStr>, pub build_id: Option<RcStr>,
/// Options for draft mode.
pub preview_props: Option<NapiDraftModeOptions>, pub preview_props: Option<NapiDraftModeOptions>,
/// The browserslist query to use for targeting browsers.
pub browserslist_query: Option<RcStr>, pub browserslist_query: Option<RcStr>,
/// Whether to write the route hashes manifest.
pub write_routes_hashes_manifest: Option<bool>, pub write_routes_hashes_manifest: Option<bool>,
/// When the code is minified, this opts out of the default mangling of
/// local names for variables, functions etc., which can be useful for
/// debugging/profiling purposes.
pub no_mangling: Option<bool>, pub no_mangling: Option<bool>,
} }
......
...@@ -354,48 +354,25 @@ export interface NapiOptionEnvVar { ...@@ -354,48 +354,25 @@ export interface NapiOptionEnvVar {
value?: RcStr value?: RcStr
} }
/** [NapiProjectOptions] with all fields optional. */ /**
* The subset of [`NapiProjectOptions`] that may change without restarting the process. Used by
* [`project_update`].
*
* Refer to [`NapiProjectOptions`] for documentation on this struct's fields.
*/
export interface NapiPartialProjectOptions { export interface NapiPartialProjectOptions {
/**
* An absolute root path (Unix or Windows path) from which all files must be nested under.
* Trying to access a file outside this root will fail, so think of this as a chroot.
* E.g. `/home/user/projects/my-repo`.
*/
rootPath?: RcStr rootPath?: RcStr
/**
* A path which contains the app/pages directories, relative to [`Project::root_path`], always
* a Unix path.
* E.g. `apps/my-app`
*/
projectPath?: RcStr projectPath?: RcStr
/** Filesystem watcher options. */
watch?: NapiWatchOptions watch?: NapiWatchOptions
/** The contents of next.config.js, serialized to JSON. */
nextConfig?: RcStr nextConfig?: RcStr
/** A map of environment variables to use when compiling code. */
env?: Array<NapiEnvVar> env?: Array<NapiEnvVar>
/**
* A map of environment variables which should get injected at compile
* time.
*/
defineEnv?: NapiDefineEnv defineEnv?: NapiDefineEnv
/** The mode in which Next.js is running. */
dev?: boolean dev?: boolean
/** The server actions encryption key. */
encryptionKey?: RcStr encryptionKey?: RcStr
/** The build id. */
buildId?: RcStr buildId?: RcStr
/** Options for draft mode. */
previewProps?: NapiDraftModeOptions previewProps?: NapiDraftModeOptions
/** The browserslist query to use for targeting browsers. */
browserslistQuery?: RcStr browserslistQuery?: RcStr
/** Whether to write the route hashes manifest. */
writeRoutesHashesManifest?: boolean writeRoutesHashesManifest?: boolean
/**
* When the code is minified, this opts out of the default mangling of
* local names for variables, functions etc., which can be useful for
* debugging/profiling purposes.
*/
noMangling?: boolean noMangling?: boolean
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment