Improve docs of language detection utils

1 files changed, 9 insertions, 3 deletions

diff --git a/src/util/language.rs b/src/util/language.rs
index c0f9c0d..69c4f6c 100644
--- a/src/util/language.rs
+++ b/src/util/language.rs
@@ -4,10 +4,10 @@ use std::path::Path;
 
 /// Detects a Markdown code-fence language tag from a filename and file contents.
 ///
-/// Extension-based detection is tried first. If the extension is unknown, the
-/// first line is inspected for a shebang.
+/// Extension-based detection takes priority over shebang detection. This means a file such as
+/// `main.py` is treated as Python even if its first line contains a different shebang.
 ///
-/// Returns an empty string when no language is detected.
+/// Returns an empty string when no language is detected fence.
 pub fn detect_language(filename: &Path, contents: &str) -> &'static str {
     detect_from_extension(filename)
         .or_else(|| detect_from_shebang(contents))
@@ -15,6 +15,9 @@ pub fn detect_language(filename: &Path, contents: &str) -> &'static str {
 }
 
 /// Detects a language tag from the file extension.
+///
+/// Extensions are matched case-insensitively. Unknown extensions return `None` so shebang detection
+/// can be attempted.
 fn detect_from_extension(filename: &Path) -> Option<&'static str> {
     let ext = filename
         .extension()
@@ -34,6 +37,9 @@ fn detect_from_extension(filename: &Path) -> Option<&'static str> {
 }
 
 /// Detects a language tag from a shebang on the first line.
+///
+/// Only a small set of common script interpreters is recognized. Shell scripts are mapped to `bash`
+/// for broad Markdown renderer compatibility.
 fn detect_from_shebang(contents: &str) -> Option<&'static str> {
     if let Some(first_line) = contents.lines().next()
         && first_line.starts_with("#!")