fix: more docs

Author: longlho

BUILD.bazel

@@ -13,6 +13,6 @@ package_metadata(
 
 license(
     name = "license",
-    kind = "@package_metadata//licenses/spdx:Apache-2.0",
+    kind = "@package_metadata//licenses/spdx:MIT",
     text = "LICENSE",
 )

MODULE.bazel.lock

@@ -1,16 +1,33 @@
-"""Aspect for aggregating extracted messages across dependency trees
-
-This aspect collects all extracted messages from a target and its dependencies,
-merging them into a single JSON file.
+"""Rules and aspects for aggregating messages across dependency trees.
+
+This module provides tools for merging extracted messages from multiple targets
+and their dependencies into a single, consolidated JSON file. This is useful for
+large monorepo projects where messages are extracted from multiple packages or
+modules and need to be combined for translation or compilation.
+
+The aggregation process:
+1. Traverses the dependency graph collecting all extracted message files
+2. Merges messages using jq with object multiplication semantics
+3. Sorts keys alphabetically for deterministic output
+4. Handles duplicate message IDs (later values override earlier ones)
+
+Aggregation can be used via:
+- `formatjs_aggregate` rule: Declarative approach for common use cases
+- `formatjs_aggregate_aspect`: Aspect-based approach for advanced scenarios
 """
 
 load(":extract.bzl", "FormatjsExtractInfo")
 
 FormatjsAggregateInfo = provider(
-    doc = "Aggregated messages from a target and its dependencies",
+    doc = """Provider containing aggregated messages from multiple targets.
+
+    This provider is returned by both the `formatjs_aggregate` rule and the
+    `formatjs_aggregate_aspect`. It contains the collected message files and
+    metadata about the aggregation.
+    """,
     fields = {
-        "messages": "depset of message JSON files",
-        "count": "Number of message files collected",
+        "messages": "depset of message JSON files collected from the target and its dependencies",
+        "count": "Number of message files collected (integer)",
     },
 )
 
@@ -82,22 +99,40 @@ formatjs_aggregate_aspect = aspect(
     implementation = _formatjs_aggregate_aspect_impl,
     attr_aspects = ["deps", "srcs"],
     toolchains = ["@jq.bzl//jq/toolchain:type"],
-    doc = """Aspect that aggregates extracted messages across dependencies.
+    doc = """Aspect that aggregates extracted messages across dependency graphs.
 
-    This aspect collects all FormatJS extracted message files from a target and
-    its transitive dependencies, merging them into a single JSON file using jq.
+    This aspect provides a powerful way to collect and merge FormatJS messages from
+    a target and all its transitive dependencies. It automatically traverses the
+    dependency graph, collecting messages from any target that provides `FormatjsExtractInfo`.
 
-    The merge strategy uses jq's object multiplication (*) which merges objects
-    with later values overwriting earlier ones for duplicate keys.
+    ## How It Works
 
-    Usage:
-        # Aggregate messages from a target and all its dependencies
-        bazel build //path/to:target \\
-            --aspects=@rules_formatjs//formatjs:aggregate.bzl%formatjs_aggregate_aspect \\
-            --output_groups=aggregated_messages
+    The aspect:
+    1. Attaches to targets via `deps` and `srcs` attributes
+    2. Collects message files from targets with `FormatjsExtractInfo`
+    3. Recursively collects from dependencies
+    4. Merges all messages into a single JSON file using jq
+    5. Sorts keys alphabetically for deterministic builds
+
+    ## Merge Strategy
 
-        # Get all individual message files (not merged)
-        bazel build //path/to:target \\
+    Messages are merged using jq's object multiplication (`*`) operator:
+    - Later values override earlier ones for duplicate message IDs
+    - All unique message IDs are preserved
+    - Sorted alphabetically by key in the final output
+
+    ## Usage Patterns
+
+    ### Basic aspect usage - aggregate all messages:
+    ```bash
+    bazel build //app:main \\
+        --aspects=@rules_formatjs//formatjs:aggregate.bzl%formatjs_aggregate_aspect \\
+        --output_groups=aggregated_messages
+    ```
+
+    ### Get individual message files (not merged):
+    ```bash
+    bazel build //app:main \\
             --aspects=@rules_formatjs//formatjs:aggregate.bzl%formatjs_aggregate_aspect \\
             --output_groups=all_messages
 
@@ -168,31 +203,173 @@ formatjs_aggregate = rule(
     implementation = _formatjs_aggregate_impl,
     attrs = {
         "deps": attr.label_list(
-            doc = "Dependencies to aggregate messages from. Should be formatjs_extract targets.",
+            doc = """Dependencies to aggregate messages from.
+
+            Should be `formatjs_extract` targets or other targets that provide
+            `FormatjsExtractInfo`. The rule will automatically apply the
+            `formatjs_aggregate_aspect` to traverse the entire dependency graph
+            and collect all messages.
+
+            Example:
+            ```starlark
+            deps = [
+                "//frontend:messages",
+                "//backend:messages",
+                "//shared:messages",
+            ]
+            ```
+            """,
             aspects = [formatjs_aggregate_aspect],
         ),
     },
     toolchains = ["@jq.bzl//jq/toolchain:type"],
-    doc = """Rule that aggregates messages from dependencies.
+    doc = """Aggregate messages from multiple extraction targets into a single file.
 
-    This rule automatically applies the formatjs_aggregate_aspect to traverse
-    dependencies and collect all messages, then merges them into a single JSON file.
+    This rule provides a declarative way to merge messages from multiple `formatjs_extract`
+    targets across your codebase. It's ideal for monorepos where messages are extracted
+    from different packages or modules and need to be combined for translation workflows.
 
-    Example:
-        ```starlark
-        formatjs_aggregate(
-            name = "all_messages",
-            deps = [
-                "//module1:messages",
-                "//module2:messages",
-                "//module3:messages",
-            ],
-        )
+    ## Features
+
+    - **Automatic Traversal**: Automatically applies aspect to collect messages from dependencies
+    - **Transitive Collection**: Gathers messages from the entire dependency graph
+    - **Merge & Sort**: Merges all messages and sorts keys alphabetically
+    - **Duplicate Handling**: Later values override earlier ones for duplicate message IDs
+    - **Simple API**: Just list your extraction targets as deps
+
+    ## How It Works
+
+    1. The rule attaches `formatjs_aggregate_aspect` to all `deps`
+    2. The aspect traverses the dependency graph collecting message files
+    3. All collected messages are merged using jq
+    4. Keys are sorted alphabetically for deterministic output
+    5. Result is written to `<name>.json`
+
+    ## Use Cases
+
+    ### Monorepo with multiple packages:
+    ```starlark
+    # Package 1 - Frontend
+    formatjs_extract(
+        name = "frontend_messages",
+        srcs = glob(["frontend/**/*.tsx"]),
+    )
+
+    # Package 2 - Backend
+    formatjs_extract(
+        name = "backend_messages",
+        srcs = glob(["backend/**/*.tsx"]),
+    )
+
+    # Aggregate all messages
+    formatjs_aggregate(
+        name = "all_messages",
+        deps = [
+            ":frontend_messages",
+            ":backend_messages",
+        ],
+    )
+    ```
+
+    ### Multi-module application:
+    ```starlark
+    formatjs_aggregate(
+        name = "app_messages",
+        deps = [
+            "//modules/auth:messages",
+            "//modules/dashboard:messages",
+            "//modules/settings:messages",
+            "//modules/admin:messages",
+        ],
+    )
+    ```
+
+    ### Nested aggregation:
+    ```starlark
+    # Aggregate messages per feature
+    formatjs_aggregate(
+        name = "feature_a_messages",
+        deps = [
+            "//features/a/component1:messages",
+            "//features/a/component2:messages",
+        ],
+    )
+
+    # Aggregate all features
+    formatjs_aggregate(
+        name = "all_features",
+        deps = [
+            ":feature_a_messages",
+            "//features/b:messages",
+            "//features/c:messages",
+        ],
+    )
+    ```
+
+    ## Output
+
+    The rule produces a JSON file named `<target_name>.json` in bazel-bin:
+    ```bash
+    bazel build //:all_messages
+    # Output: bazel-bin/all_messages.json
+    ```
+
+    The output format is standard FormatJS JSON:
+    ```json
+    {
+      "app.auth.login": {
+        "id": "app.auth.login",
+        "defaultMessage": "Log in",
+        "description": "Login button"
+      },
+      "app.dashboard.welcome": {
+        "id": "app.dashboard.welcome",
+        "defaultMessage": "Welcome back!",
+        "description": "Dashboard greeting"
+      }
+    }
+    ```
+
+    ## Duplicate Message IDs
+
+    If the same message ID appears in multiple sources, the last one wins:
+    - Messages are merged in the order they appear in the dependency graph
+    - Later definitions override earlier ones
+    - This allows for intentional overrides (e.g., customizing messages per module)
+
+    ## Usage in Translation Workflow
+
+    ```starlark
+    # 1. Aggregate all messages
+    formatjs_aggregate(
+        name = "source_messages",
+        deps = ["//..."],  # All extraction targets
+    )
+
+    # 2. Verify translations
+    formatjs_verify_test(
+        name = "verify_translations",
+        translations = [
+            ":source_messages",
+            "translations/fr.json",
+            "translations/de.json",
+        ],
+    )
+
+    # 3. Compile for production
+    formatjs_compile(
+        name = "compiled_fr",
+        src = "translations/fr.json",
+        out = "compiled-fr.json",
+        ast = True,
+    )
+    ```
+
+    ## See Also
 
-        # Simply build the target to get the aggregated messages:
-        # bazel build //:all_messages
-        #
-        # The output will be at: bazel-bin/all_messages.json
-        ```
+    - `formatjs_extract`: Extract messages from source files
+    - `formatjs_aggregate_aspect`: Lower-level aspect for advanced use cases
+    - `formatjs_verify_test`: Verify translations against aggregated messages
+    - `formatjs_compile`: Compile aggregated messages for production
     """,
 )