From b9583bb16a7fd1e9ce31ae36110ef51ead73ac7d Mon Sep 17 00:00:00 2001
From: Daniel Rainer <daniel.rainer@localhost>
Date: Fri, 6 Jun 2025 23:59:43 +0200
Subject: [PATCH] Document call sites of `from_external_source`

This is intended to provide information to programmers where localizations might
be coming from, and potentially help with analyzing issues with localizations.
---
 src/builtins/function.rs | 2 ++
 src/builtins/shared.rs   | 4 ++++
 src/complete.rs          | 2 ++
 src/function.rs          | 2 ++
 4 files changed, 10 insertions(+)

diff --git a/src/builtins/function.rs b/src/builtins/function.rs
index c9b404981..61c698ea4 100644
--- a/src/builtins/function.rs
+++ b/src/builtins/function.rs
@@ -354,6 +354,8 @@ pub fn function(
     let props = function::FunctionProperties {
         func_node,
         named_arguments: opts.named_arguments,
+        // Function descriptions are extracted from scripts in `share` via
+        // `build_tools/fish_xgettext.fish`.
         description: LocalizableString::from_external_source(opts.description),
         inherit_vars: inherit_vars.into_boxed_slice(),
         shadow_scope: opts.shadow_scope,
diff --git a/src/builtins/shared.rs b/src/builtins/shared.rs
index b7b5dcfbb..2ca4510b4 100644
--- a/src/builtins/shared.rs
+++ b/src/builtins/shared.rs
@@ -1033,6 +1033,10 @@ fn builtin_false(_parser: &Parser, _streams: &mut IoStreams, _argv: &mut [&wstr]
     Err(STATUS_CMD_ERROR)
 }
 
+/// Used for the fish `_` builtin for requesting translations.
+/// For scripts in `share/`, the corresponding strings are extracted from the scripts using
+/// `build_tools/fish_xgettext.fish`.
+/// Strings not present in our repo would require a custom MO file for translation to be possible.
 fn builtin_gettext(_parser: &Parser, streams: &mut IoStreams, argv: &mut [&wstr]) -> BuiltinResult {
     for arg in &argv[1..] {
         streams.out.append(
diff --git a/src/complete.rs b/src/complete.rs
index f1baff722..a7c0ba99a 100644
--- a/src/complete.rs
+++ b/src/complete.rs
@@ -2303,6 +2303,8 @@ pub fn complete_add(
         typ: option_type,
         result_mode,
         comp,
+        // The external source is a completion script in `share`,
+        // from which `build_tools/fish_xgettext.fish` extracts descriptions.
         desc: LocalizableString::from_external_source(desc),
         conditions: condition,
         flags,
diff --git a/src/function.rs b/src/function.rs
index 72b847297..963f22151 100644
--- a/src/function.rs
+++ b/src/function.rs
@@ -294,6 +294,8 @@ pub(crate) fn set_desc(name: &wstr, desc: WString, parser: &Parser) {
         // Note the description is immutable, as it may be accessed on another thread, so we copy
         // the properties to modify it.
         let mut new_props = props.as_ref().clone();
+        // Translations will only be available if the function description has been extracted into
+        // the translation files available to fish.
         new_props.description = LocalizableString::from_external_source(desc);
         funcset.funcs.insert(name.to_owned(), Arc::new(new_props));
     }