Skip to content

Commit c115657

Browse files
bgwbgw
authored
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.
1 parent e674165 commit c115657

3 files changed

Lines changed: 30 additions & 82 deletions

File tree

‎crates/next-api/src/project.rs‎

Lines changed: 20 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -289,13 +289,18 @@ impl DebugBuildPathsRouteKeys {
289289
)]
290290
#[serde(rename_all = "camelCase")]
291291
pub struct ProjectOptions {
292-
/// An absolute root path (Unix or Windows path) from which all files must be nested under.
293-
/// Trying to access a file outside this root will fail, so think of this as a chroot.
294-
/// E.g. `/home/user/projects/my-repo`.
292+
/// An [canonicalized][std::fs::canonicalize] root path (Unix or Windows path) from which all
293+
/// files must be nested under. Trying to access a file outside this root will fail, so think
294+
/// of this as a weak chroot. E.g. `/home/user/projects/my-repo`.
295+
///
296+
/// This serves two purposes:
297+
/// - It gives us a root to configure the file system watcher with.
298+
/// - It ensures the cache is portable when the root path is moved, since every other path is
299+
/// relative to it.
295300
pub root_path: RcStr,
296301

297-
/// A path which contains the app/pages directories, relative to [`Project::project_path`],
298-
/// always Unix path. E.g. `apps/my-app`
302+
/// A path which contains the app/pages directories, relative to [`Project::project_path`].
303+
/// Always a Unix-style (`/`-separated) path. E.g. `apps/my-app`.
299304
pub project_path: RcStr,
300305

301306
/// The contents of next.config.js, serialized to JSON.
@@ -304,8 +309,7 @@ pub struct ProjectOptions {
304309
/// A map of environment variables to use when compiling code.
305310
pub env: Vec<(RcStr, RcStr)>,
306311

307-
/// A map of environment variables which should get injected at compile
308-
/// time.
312+
/// A map of environment variables which should get injected at compile time.
309313
pub define_env: DefineEnv,
310314

311315
/// Filesystem watcher options.
@@ -326,9 +330,8 @@ pub struct ProjectOptions {
326330
/// The browserslist query to use for targeting browsers.
327331
pub browserslist_query: RcStr,
328332

329-
/// When the code is minified, this opts out of the default mangling of
330-
/// local names for variables, functions etc., which can be useful for
331-
/// debugging/profiling purposes.
333+
/// When the code is minified, this opts out of the default mangling of local names for
334+
/// variables, functions etc., which can be useful for debugging/profiling purposes.
332335
pub no_mangling: bool,
333336

334337
/// Whether to write the route hashes manifest.
@@ -337,8 +340,8 @@ pub struct ProjectOptions {
337340
/// The version of Node.js that is available/currently running.
338341
pub current_node_js_version: RcStr,
339342

340-
/// Debug build paths for selective builds.
341-
/// When set, only routes matching these paths will be included in the build.
343+
/// Debug build paths for selective builds. When set, only routes matching these paths will be
344+
/// included in the build.
342345
pub debug_build_paths: Option<DebugBuildPaths>,
343346

344347
/// App-router page routes that should be built after non-deferred routes.
@@ -350,57 +353,42 @@ pub struct ProjectOptions {
350353
/// The version of Next.js that is running.
351354
pub next_version: RcStr,
352355

353-
/// Whether server-side HMR is enabled (disabled with --no-server-fast-refresh).
356+
/// Whether server-side HMR is enabled (disabled with `--no-server-fast-refresh`).
354357
pub server_hmr: bool,
355358
}
356359

360+
/// The subset of [`ProjectOptions`] that may change without restarting the process. Used by
361+
/// [`ProjectContainer::update`].
362+
///
363+
/// Refer to [`ProjectOptions`] for documentation on this struct's fields.
357364
#[derive(Default)]
358365
pub struct PartialProjectOptions {
359-
/// A root path from which all files must be nested under. Trying to access
360-
/// a file outside this root will fail. Think of this as a chroot.
361366
pub root_path: Option<RcStr>,
362367

363-
/// A path inside the root_path which contains the app/pages directories.
364368
pub project_path: Option<RcStr>,
365369

366-
/// The contents of next.config.js, serialized to JSON.
367370
pub next_config: Option<RcStr>,
368371

369-
/// A map of environment variables to use when compiling code.
370372
pub env: Option<Vec<(RcStr, RcStr)>>,
371373

372-
/// A map of environment variables which should get injected at compile
373-
/// time.
374374
pub define_env: Option<DefineEnv>,
375375

376-
/// Filesystem watcher options.
377376
pub watch: Option<WatchOptions>,
378377

379-
/// The mode in which Next.js is running.
380378
pub dev: Option<bool>,
381379

382-
/// The server actions encryption key.
383380
pub encryption_key: Option<RcStr>,
384381

385-
/// The build id.
386382
pub build_id: Option<RcStr>,
387383

388-
/// Options for draft mode.
389384
pub preview_props: Option<DraftModeOptions>,
390385

391-
/// The browserslist query to use for targeting browsers.
392386
pub browserslist_query: Option<RcStr>,
393387

394-
/// When the code is minified, this opts out of the default mangling of
395-
/// local names for variables, functions etc., which can be useful for
396-
/// debugging/profiling purposes.
397388
pub no_mangling: Option<bool>,
398389

399-
/// Whether to write the route hashes manifest.
400390
pub write_routes_hashes_manifest: Option<bool>,
401391

402-
/// Debug build paths for selective builds.
403-
/// When set, only routes matching these paths will be included in the build.
404392
pub debug_build_paths: Option<DebugBuildPaths>,
405393
}
406394

‎crates/next-napi-bindings/src/next_api/project.rs‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -220,53 +220,36 @@ pub struct NapiProjectOptions {
220220
pub server_hmr: Option<bool>,
221221
}
222222

223-
/// [NapiProjectOptions] with all fields optional.
223+
/// The subset of [`NapiProjectOptions`] that may change without restarting the process. Used by
224+
/// [`project_update`].
225+
///
226+
/// Refer to [`NapiProjectOptions`] for documentation on this struct's fields.
224227
#[napi(object)]
225228
pub struct NapiPartialProjectOptions {
226-
/// An absolute root path (Unix or Windows path) from which all files must be nested under.
227-
/// Trying to access a file outside this root will fail, so think of this as a chroot.
228-
/// E.g. `/home/user/projects/my-repo`.
229229
pub root_path: Option<RcStr>,
230230

231-
/// A path which contains the app/pages directories, relative to [`Project::root_path`], always
232-
/// a Unix path.
233-
/// E.g. `apps/my-app`
234231
pub project_path: Option<RcStr>,
235232

236-
/// Filesystem watcher options.
237233
pub watch: Option<NapiWatchOptions>,
238234

239-
/// The contents of next.config.js, serialized to JSON.
240235
pub next_config: Option<RcStr>,
241236

242-
/// A map of environment variables to use when compiling code.
243237
pub env: Option<Vec<NapiEnvVar>>,
244238

245-
/// A map of environment variables which should get injected at compile
246-
/// time.
247239
pub define_env: Option<NapiDefineEnv>,
248240

249-
/// The mode in which Next.js is running.
250241
pub dev: Option<bool>,
251242

252-
/// The server actions encryption key.
253243
pub encryption_key: Option<RcStr>,
254244

255-
/// The build id.
256245
pub build_id: Option<RcStr>,
257246

258-
/// Options for draft mode.
259247
pub preview_props: Option<NapiDraftModeOptions>,
260248

261-
/// The browserslist query to use for targeting browsers.
262249
pub browserslist_query: Option<RcStr>,
263250

264-
/// Whether to write the route hashes manifest.
265251
pub write_routes_hashes_manifest: Option<bool>,
266252

267-
/// When the code is minified, this opts out of the default mangling of
268-
/// local names for variables, functions etc., which can be useful for
269-
/// debugging/profiling purposes.
270253
pub no_mangling: Option<bool>,
271254
}
272255

‎packages/next/src/build/swc/generated-native.d.ts‎

Lines changed: 6 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -354,48 +354,25 @@ export interface NapiOptionEnvVar {
354354
value?: RcStr
355355
}
356356

357-
/** [NapiProjectOptions] with all fields optional. */
357+
/**
358+
* The subset of [`NapiProjectOptions`] that may change without restarting the process. Used by
359+
* [`project_update`].
360+
*
361+
* Refer to [`NapiProjectOptions`] for documentation on this struct's fields.
362+
*/
358363
export interface NapiPartialProjectOptions {
359-
/**
360-
* An absolute root path (Unix or Windows path) from which all files must be nested under.
361-
* Trying to access a file outside this root will fail, so think of this as a chroot.
362-
* E.g. `/home/user/projects/my-repo`.
363-
*/
364364
rootPath?: RcStr
365-
/**
366-
* A path which contains the app/pages directories, relative to [`Project::root_path`], always
367-
* a Unix path.
368-
* E.g. `apps/my-app`
369-
*/
370365
projectPath?: RcStr
371-
/** Filesystem watcher options. */
372366
watch?: NapiWatchOptions
373-
/** The contents of next.config.js, serialized to JSON. */
374367
nextConfig?: RcStr
375-
/** A map of environment variables to use when compiling code. */
376368
env?: Array<NapiEnvVar>
377-
/**
378-
* A map of environment variables which should get injected at compile
379-
* time.
380-
*/
381369
defineEnv?: NapiDefineEnv
382-
/** The mode in which Next.js is running. */
383370
dev?: boolean
384-
/** The server actions encryption key. */
385371
encryptionKey?: RcStr
386-
/** The build id. */
387372
buildId?: RcStr
388-
/** Options for draft mode. */
389373
previewProps?: NapiDraftModeOptions
390-
/** The browserslist query to use for targeting browsers. */
391374
browserslistQuery?: RcStr
392-
/** Whether to write the route hashes manifest. */
393375
writeRoutesHashesManifest?: boolean
394-
/**
395-
* When the code is minified, this opts out of the default mangling of
396-
* local names for variables, functions etc., which can be useful for
397-
* debugging/profiling purposes.
398-
*/
399376
noMangling?: boolean
400377
}
401378

0 commit comments

Comments
 (0)