docs(rollup): improve clarity

internal/providers/linkable_package_info.bzl

@@ -29,13 +29,13 @@ In the future, the linker may validate that the names match the name in a packag
 
 Path must be relative to execroot/wksp. It can either an output dir path such as,
 
-`bazel-out/<platform>-<build>/bin/path/to/package` or
-`bazel-out/<platform>-<build>/bin/external/&llt;external_wksp>/path/to/package`
+`bazel-out/<platform>-<build>/bin/path/to/package` or
+`bazel-out/<platform>-<build>/bin/external/external_wksp>/path/to/package`
 
 or a source file path such as,
 
 `path/to/package` or
-`external/&lt;external_wksp&gt;/path/to/package`
+`external/<external_wksp>/path/to/package`
 """,
         "_tslibrary": "For internal use only",
     },

packages/rollup/install.md

@@ -1,12 +1,12 @@
 # Rollup rules for Bazel
 
-The Rollup rules run the Rollup.JS bundler with Bazel.
+The Rollup rules run the [rollup.js](https://rollupjs.org/) bundler with Bazel.
 
 ## Installation
 
 Add the `@bazel/rollup` npm package to your `devDependencies` in `package.json`.
 
-## Installing with self-managed dependencies
+### Installing with self-managed dependencies
 
 If you didn't use the `yarn_install` or `npm_install` rule, you'll have to declare a rule in your root `BUILD.bazel` file to execute rollup:
 
@@ -23,7 +23,7 @@ nodejs_binary(
 
 ## Usage
 
-The `rollup_bundle` rule is used to invoke Rollup.js on some inputs.
+The `rollup_bundle` rule is used to invoke Rollup on some JavaScript inputs.
 The API docs appear [below](#rollup_bundle).
 
 Typical example:
@@ -50,15 +50,17 @@ module.exports = {
 }
 ```
 
-## Output types
+### Output types
 
-You must determine ahead of time whether Rollup needs to produce a directory output.
-This is the case if you have dynamic imports which cause code-splitting, or if you
+You must determine ahead of time whether Rollup will write a single file or a directory.
+Rollup's CLI has the same behavior, forcing you to pick `--output.file` or `--output.dir`.
+
+Writing a directory is used when you have dynamic imports which cause code-splitting, or if you
 provide multiple entry points. Use the `output_dir` attribute to specify that you want a
 directory output.
-Rollup's CLI has the same behavior, forcing you to pick `--output.file` or `--output.dir`.
 
-To get multiple output formats, wrap the rule with a macro or list comprehension, e.g.
+Each `rollup_bundle` rule produces only one output by running the rollup CLI a single time.
+To get multiple output formats, you can wrap the rule with a macro or list comprehension, e.g.
 
 ```python
 [
@@ -76,24 +78,24 @@ To get multiple output formats, wrap the rule with a macro or list comprehension
 
 This will produce one output per requested format.
 
-## Stamping
+### Stamping
 
 You can stamp the current version control info into the output by writing some code in your rollup config.
 See the [stamping documentation](stamping).
 
 By passing the `--stamp` option to Bazel, two additional input files will be readable by Rollup.
 
-1. The variable `bazel_version_file` will point to the path of Bazel's "volatile-status.txt" file which contains
+1. The variable `bazel_version_file` will point to `bazel-out/volatile-status.txt` which contains
 statuses that change frequently; such changes do not cause a re-build of the rollup_bundle.
-2. The variable `bazel_info_file` will point to the path of Bazel's "stable-status.txt" file which contains
+2. The variable `bazel_info_file` will point to `bazel-out/stable-status.txt` file which contains
 statuses that stay the same; any changed values will cause rollup_bundle to rebuild.
 
 Both `bazel_version_file` and `bazel_info_file` will be `undefined` if the build is run without `--stamp`.
 
-> Note that under `--stamp`, only the bundling is re-built, but not all the compilation steps.
+> Note that under `--stamp`, only the bundle is re-built, but not the compilation steps that produced the inputs.
 > This avoids a slow cascading re-build of a whole tree of actions.
 
-To use these files, just write JS code in the rollup.config.js that reads one of the status files and parses the lines.
+To use these files, you write JS code in your `rollup.config.js` to read from the status files and parse the lines.
 Each line is a space-separated key/value pair.
 
 ```javascript
@@ -110,10 +112,10 @@ if (bazel_info_file) {
 }
 ```
 
-## Debug and Opt builds
+### Debug and Opt builds
 
 When you use `--compilation_mode=dbg`, Bazel produces a distinct output-tree in `bazel-out/[arch]-dbg/bin`.
-Code in your rollup.config.js can look in the environment to detect if a Debug build is being performed,
+Code in your `rollup.config.js` can look in the environment to detect if a debug build is being performed,
 and include extra developer information in the bundle that you wouldn't normally ship to production.
 
 Similarly, `--compilation_mode=opt` is Bazel's signal to perform extra optimizations.
@@ -124,3 +126,31 @@ For example you could define a constant for enabling Debug:
 ```javascript
 const DEBUG = process.env['COMPILATION_MODE'] === 'dbg';
 ```
+
+and configure Rollup differently when `DEBUG` is `true` or `false`.
+
+### Increasing Heap memory for rollup
+
+The `rollup_bin` attribute allows you to customize the rollup.js program we execute,
+so you can use `nodejs_binary` to construct your own.
+
+> You can always call `bazel query --output=build [default rollup_bin]` to see what
+> the default definition looks like, then copy-paste from there to be sure yours
+> matches.
+
+```python
+nodejs_binary(
+    name = "rollup_more_mem",
+    data = ["@npm//rollup:rollup"],
+    entry_point = "@npm//:node_modules/rollup/dist/bin/rollup",
+    templated_args = [
+        "--nobazel_patch_module_resolver",
+        "--node_options=--max-old-space-size=<SOME_SIZE>",
+    ],
+)
+
+rollup_bundle(
+    ...
+    rollup_bin = ":rollup_more_mem",
+)
+```

packages/rollup/rollup_bundle.bzl

@@ -3,27 +3,22 @@
 load("@build_bazel_rules_nodejs//:providers.bzl", "JSEcmaScriptModuleInfo", "JSModuleInfo", "NODE_CONTEXT_ATTRS", "NodeContextInfo", "NpmPackageInfo", "node_modules_aspect", "run_node")
 load("@build_bazel_rules_nodejs//internal/linker:link_node_modules.bzl", "module_mappings_aspect")
 
-_DOC = """Runs the Rollup.js CLI under Bazel.
-
-See [the Rollup CLI reference](https://rollupjs.org/guide/en/#command-line-reference)
-"""
+_DOC = "Runs the rollup.js CLI under Bazel."
 
 _ROLLUP_ATTRS = dict(NODE_CONTEXT_ATTRS, **{
     "args": attr.string_list(
-        doc = """Command line arguments to pass to rollup. Can be used to override config file settings.
+        doc = """Command line arguments to pass to Rollup. Can be used to override config file settings.
 
-These argument passed on the command line before all arguments that are always added by the
-rule such as `--output.dir` or `--output.file`, `--format`, `--config` and `--preserveSymlinks` and
-also those that are optionally added by the rule such as `--sourcemap`.
+These argument passed on the command line before arguments that are added by the rule.
+Run `bazel` with `--subcommands` to see what Rollup CLI command line was invoked.
 
-See rollup CLI docs https://rollupjs.org/guide/en/#command-line-flags for complete list of supported arguments.""",
+See the <a href="https://rollupjs.org/guide/en/#command-line-flags">Rollup CLI docs</a> for a complete list of supported arguments.""",
         default = [],
     ),
     "config_file": attr.label(
-        doc = """A rollup.config.js file
+        doc = """A `rollup.config.js` file
 
-Passed to the --config 
-See https://rollupjs.org/guide/en/#configuration-files
+Passed to the `--config` option, see [the config doc](https://rollupjs.org/guide/en/#configuration-files)
 
 If not set, a default basic Rollup config is used.
 """,
@@ -93,7 +88,7 @@ Either this attribute or `entry_point` must be specified, but not both.
         allow_files = True,
     ),
     "format": attr.string(
-        doc = """"Specifies the format of the generated bundle. One of the following:
+        doc = """Specifies the format of the generated bundle. One of the following:
 
 - `amd`: Asynchronous Module Definition, used with module loaders like RequireJS
 - `cjs`: CommonJS, suitable for Node and other bundlers