[clang] [clang][NFC] add comments for canBeJoined function (PR #150766)

[Jongmyeong Choi via cfe-commits]

https://github.com/jongmyeong-choi created https://github.com/llvm/llvm-project/pull/150766

- Convert simple comment to detailed Doxygen-style documentation
- Add comprehensive examples of token concatenation cases
- Include examples of safe adjacency cases
- Clarify the function's purpose and return value semantics

>From 0fd412fbe454a461881d479b3a5cc8fc732f0513 Mon Sep 17 00:00:00 2001
From: Jongmyeong Choi <cheesechoi at gmail.com>
Date: Sat, 26 Jul 2025 19:04:02 +0900
Subject: [PATCH] [clang][NFC] add comments for canBeJoined function

- Convert simple comment to detailed Doxygen-style documentation
- Add comprehensive examples of token concatenation cases
- Include examples of safe adjacency cases
- Clarify the function's purpose and return value semantics
---
 clang/lib/Edit/EditedSource.cpp | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/clang/lib/Edit/EditedSource.cpp b/clang/lib/Edit/EditedSource.cpp
index 398cce71d5e27..04b0f794055b3 100644
--- a/clang/lib/Edit/EditedSource.cpp
+++ b/clang/lib/Edit/EditedSource.cpp
@@ -308,7 +308,23 @@ bool EditedSource::commit(const Commit &commit) {
   return true;
 }
 
-// Returns true if it is ok to make the two given characters adjacent.
+/// Checks if two characters can be placed adjacent without creating unintended tokens.
+///
+/// Returns false when adjacency would cause token concatenation:
+///   - 'a' + 'b' → "ab" (different identifier)  
+///   - '<' + '<' → "<<" (shift operator)
+///   - '+' + '+' → "++" (increment operator)
+///   - '/' + '*' → "/*" (comment start)
+///
+/// Returns true when adjacency is safe:
+///   - 'a' + ')' → "a)" (separate tokens)
+///   - '5' + ')' → "5)" (separate tokens)
+///
+/// Used by adjustRemoval() to decide whether to insert space during text removal.
+///
+/// @param left Character on the left side
+/// @param right Character on the right side
+/// @return true if safe to place adjacent, false if space needed
 static bool canBeJoined(char left, char right, const LangOptions &LangOpts) {
   // FIXME: Should use TokenConcatenation to make sure we don't allow stuff like
   // making two '<' adjacent.