[llvm] [llvm-link] Add more detail to `--internalize` description (PR #170397)

[Matthew Maurer via llvm-commits]

https://github.com/maurer created https://github.com/llvm/llvm-project/pull/170397

While the functionality of this flag is obvious in the implementation, tool users may not know what it does with the short description provided. Notably, it is not obvious from the short description that:

* Functions provided will be converted to internal linkage (and thus discarded if unused) even if unreferenced.
* Functions in the first file will not be internalized, even if referenced by a later one.

The Rust for Linux project has [found use for this flag](https://lore.kernel.org/all/20251202-inline-helpers-v1-0-879dae33a66a@google.com/) to support inlining `static inline` functions in C into code compiled by Rust when `rustc` and `clang` share a LLVM.

I wanted to send this PR both to:
1. Help others find the flag in the future
2. Clarify that our understanding of what we can rely upon this option to do is correct, and not just what the implementation happens to do at the moment.

cc @Darksonn (also with Rust-for-Linux)

cc @nikic Perhaps able to review or route us to an appropriate reviewer?

>From 4167bd1b44527a17de240ac476b467fdfb4cdedc Mon Sep 17 00:00:00 2001
From: Matthew Maurer <mmaurer at google.com>
Date: Wed, 3 Dec 2025 00:20:54 +0000
Subject: [PATCH] [llvm-link] Add more detail to `--internalize` description

While the functionality of this flag is obvious in the implementation,
tool users may not know what it does with the short description
provided. Notably, it is not obvious from the short description that:

* Functions provided will be converted to internal linkage (and thus
  discarded if unused) even if unreferenced.
* Functions in the first file will not be internalized, even if
  referenced by a later one.
---
 llvm/tools/llvm-link/llvm-link.cpp | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/llvm/tools/llvm-link/llvm-link.cpp b/llvm/tools/llvm-link/llvm-link.cpp
index 33c3e6fc350fb..fbc6c31f75c62 100644
--- a/llvm/tools/llvm-link/llvm-link.cpp
+++ b/llvm/tools/llvm-link/llvm-link.cpp
@@ -75,9 +75,12 @@ static cl::opt<std::string>
     OutputFilename("o", cl::desc("Override output filename"), cl::init("-"),
                    cl::value_desc("filename"), cl::cat(LinkCategory));
 
-static cl::opt<bool> Internalize("internalize",
-                                 cl::desc("Internalize linked symbols"),
-                                 cl::cat(LinkCategory));
+static cl::opt<bool>
+    Internalize("internalize",
+                cl::desc("Internalize linked symbols - maintains existing "
+                         "linkage for the first input and converts linkage in"
+                         " all other inputs to `internal`"),
+                cl::cat(LinkCategory));
 
 static cl::opt<bool>
     DisableDITypeMap("disable-debug-info-type-map",