From 48224c19c612e2c352f62f6bfee8d723d2a47ad0 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 11 Feb 2025 15:30:47 -0600
Subject: [PATCH] docs(embedded): Note the shebang deviation

rustc considers the following valid and without a shebang:
```rust

// Hello

[allow(dead_code)]

fn main() {
    println!("Hello, world!");
}
```
and
```rustc
[allow(dead_code)]

fn main() {
    println!("Hello, world!");
}
```

In both cases, we consider it to have a shebang.  This commit documents
that intention.

We could add our own heuristics
(e.g. `#!` with only whitespace is not a shebang)
but we should either be a subset or intentionally different than rustc
(e.g. require a non `[`-prefixes interpreter)
rather than do both.

This will be reflected in the tracking issue which will handle the final
decision for the team on this matter.

Fixes #15170
---
 src/cargo/util/toml/embedded.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/cargo/util/toml/embedded.rs b/src/cargo/util/toml/embedded.rs
index e151c4add..2257d2b8b 100644
--- a/src/cargo/util/toml/embedded.rs
+++ b/src/cargo/util/toml/embedded.rs
@@ -147,6 +147,9 @@ impl<'s> ScriptSource<'s> {
         if let Some(rest) = source.content.strip_prefix("#!") {
             // Ok, this is a shebang but if the next non-whitespace token is `[`,
             // then it may be valid Rust code, so consider it Rust code.
+            //
+            // NOTE: rustc considers line and block comments to be whitespace but to avoid
+            // any more awareness of Rust grammar, we are excluding it.
             if rest.trim_start().starts_with('[') {
                 return Ok(source);
             }