docs: explain out_dir with output_dir

Author: alexeagle

docs/swc.md

@@ -38,6 +38,7 @@ sh_test(
     deps = ["@bazel_tools//tools/bash/runfiles"],
 )
 
+# Like above, but outputs to examples/directory/test-out_dir instead.
 swc(
     name = "out_dir",
     srcs = ["split_app"],

examples/directory/BUILD.bazel

@@ -43,7 +43,10 @@ def swc(name, srcs, args = [], data = [], plugins = [], output_dir = False, swcr
         data: Files needed at runtime by binaries or tests that transitively depend on this target.
             See https://bazel.build/reference/be/common-definitions#typical-attributes
 
-        output_dir: Whether to produce a directory output rather than individual files
+        output_dir: Whether to produce a directory output rather than individual files.
+
+            If `out_dir` is set, then that is used as the name of the output directory.
+            Otherwise, the output directory is named the same as the target.
 
         args: Additional options to pass to `swcx` cli, see https://github.com/swc-project/swc/discussions/3859
             Note: we do **not** run the [NodeJS wrapper `@swc/cli`](https://swc.rs/docs/usage/cli)
@@ -61,7 +64,9 @@ def swc(name, srcs, args = [], data = [], plugins = [], output_dir = False, swcr
 
         plugins: List of plugin labels created with `swc_plugin`.
 
-        out_dir: The base directory for output files relative to the output directory for this package
+        out_dir: The base directory for output files relative to the output directory for this package.
+
+            If output_dir is True, then this is used as the name of the output directory.
 
         root_dir: A subdirectory under the input package which should be considered the root directory of all the input files
 

swc/defs.bzl

@@ -28,7 +28,10 @@ _attrs = {
         default = "false",
     ),
     "output_dir": attr.bool(
-        doc = "whether to produce a directory output rather than individual files",
+        doc = """Whether to produce a directory output rather than individual files.
+        
+        If out_dir is also specified, it is used as the name of the output directory.
+        Otherwise, the directory is named the same as the target.""",
     ),
     "data": js_lib_helpers.JS_LIBRARY_DATA_ATTR,
     "swcrc": attr.label(
@@ -40,7 +43,9 @@ _attrs = {
         providers = [[DefaultInfo, SwcPluginConfigInfo]],
     ),
     "out_dir": attr.string(
-        doc = "base directory for output files",
+        doc = """With output_dir=False, output files will have this directory prefix.
+        
+        With output_dir=True, this is the name of the output directory.""",
     ),
     "root_dir": attr.string(
         doc = "a subdirectory under the input package which should be consider the root directory of all the input files",