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

@@ -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,

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(

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,

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));
     }