From b3ef1d38e9bf9bb58f53e3f233a9109abdc75ff7 Mon Sep 17 00:00:00 2001
From: Chris Bracken <chris@bracken.jp>
Date: Wed, 17 Jul 2024 14:44:36 -0700
Subject: [PATCH] Add doc comments to build/archives/BUILD.gn
 (flutter/engine#53973)

The existing comment on gen_snapshot is unclear. Adds comments where
they were missing. Saves future readers some digging through git blame.

## Pre-launch Checklist

- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [X] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [X] I read and followed the [Flutter Style Guide] and the [C++,
Objective-C, Java style guides].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [ ] I added new tests to check the change I am making or feature I am
adding, or the PR is [test-exempt]. See [testing the engine] for
instructions on writing and running engine tests.
- [X] I updated/added relevant documentation (doc comments with `///`).
- [X] I signed the [CLA].
- [X] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[C++, Objective-C, Java style guides]:
https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
[testing the engine]:
https://github.com/flutter/flutter/wiki/Testing-the-engine
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat
---
 engine/src/flutter/build/archives/BUILD.gn | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/engine/src/flutter/build/archives/BUILD.gn b/engine/src/flutter/build/archives/BUILD.gn
index cdd9498189..809312c739 100644
--- a/engine/src/flutter/build/archives/BUILD.gn
+++ b/engine/src/flutter/build/archives/BUILD.gn
@@ -53,13 +53,16 @@ if (build_engine_artifacts && !is_android) {
       exe = ".exe"
     }
 
-    # Only include gen_snapshot for all runtime modes.
+    # gen_snapshot is bundled for all runtime modes.
     files = [
       {
         source = "$root_out_dir/gen_snapshot$exe"
         destination = "gen_snapshot$exe"
       },
     ]
+
+    # Host tooling/libraries that are used only in debug builds, or which are
+    # identical across all runtime modes.
     if (flutter_runtime_mode == "debug") {
       dll = ".so"
       lib_prefix = "lib"
@@ -109,6 +112,9 @@ if (build_engine_artifacts && !is_android) {
         },
       ]
     }
+
+    # On macOS, add entitlements.txt, which contains filenames of binaries that
+    # need to be code-signed by a later CI stage.
     if (host_os == "mac") {
       deps += [ ":artifacts_entitlement_config" ]
       files += [