Improve YARD documention

Author: AliSoftware

lib/fastlane/plugin/wpmreleasetoolkit/models/locales.rb

@@ -1,10 +1,19 @@
 module Fastlane
+  # Define a single Locale with the various locale codes depending on the representation needed
   Locale = Struct.new(:glotpress, :android, :google_play, :ios, :app_store, keyword_init: true) do
+    # Returns the Locale with the given glotpress locale code from the list of all known locales (`Locales.all`)
+    #
+    # @param [String] The glotpress locale code for the locale to fetch
+    # @return [Locale] The locale found
+    # @raise [RuntimeException] if the locale with given glotpress code is unknown
     def self.[](code)
       Locales[code].first
     end
   end
 
+  # A class with static methods to manipulate lists of locales.
+  # Exposes various `Array<Locale>` lists like all known locales, the Mag16,
+  # and convenience methods to turn list of Strings into list of Locales.
   class Locales
     ###################
     ## Constants
@@ -77,28 +86,36 @@ def all
         ALL_KNOWN_LOCALES
       end
 
-      # Define from_glotpress(code_or_list), from_android(code_or_list) … methods
+      # Define from_glotpress(code_or_list), from_android(code_or_list) … methods.
+      #
+      # Those can be used in the rare cases where you need to find locales via codes other than the glotpress ones,
+      # like searching by android locale code(s) or google_play locale code(s).
+      # In most cases, prefer using the `Locales[…]` method instead ()with glotpress locale codes).
       #
       # @param [Array<String>, String] list of locale codes to search for, or single value for single result
-      # @return [Array<Locale>, Locale] list of found locales (empty if none found), or single locale if a single value was passed (or nil if not found)
+      # @return [Array<Locale>, Locale] list of found locales, or single locale if a single value was passed
+      # @raise [RuntimeException] if at least one of the locale codes was unknown
       #
       %i[glotpress android google_play ios app_store].each do |key|
-        define_method("from_#{key}") { |args| search(key, args) }
+        define_method("from_#{key}") { |args| search!(key, args) }
       end
 
       # Return an Array<Locale> based on glotpress locale codes
       #
-      # @note If you need a single locale, you can use Locale[code] instead of Locales[code]
+      # @note If you need a single locale instead of an `Array<Locale>`, you can use Locale[code] instead of Locales[code]
+      #
       # @param [String..., Array<String>] Arbitrary list of strings, either passed as a single array parameter, or as a vararg list of params
       # @return [Array<Locale>] The found locales.
+      # @raise [RuntimeException] if at least one of the locale codes was unknown
       #
       def [](*list)
-        # If we passed an Array, `*list` will make it an Array<Array<String>>, so taking `list.first` in those cases to go back to Array<String>
+        # If we passed a variadic list of Strings, `*list` will make it a single `Array<String>` and we were already good to go.
+        # But if we passed an Array, `*list` will make it an Array<Array<String>> of one item; taking `list.first` will go back to Array<String>.
         list = list.first if list.count == 1 && list.first.is_a?(Array)
         from_glotpress(list)
       end
 
-      # Return the subset of the 16 locales most of our apps are localized 100% (what we call the "Magnificent 16")
+      # Return the subset of the 16 locales most of our apps are localized 100% (the ones we call the "Magnificent 16")
       #
       # @return [Array<Locale>] List of the Mag16 locales
       def mag16
@@ -110,17 +127,17 @@ def mag16
       private
 
       # Search the known locales for just the ones having the provided locale code, where the codes are expressed using the standard for the given key
-      def search(key, code_or_list)
+      def search!(key, code_or_list)
         if code_or_list.is_a?(Array)
-          code_or_list.map { |code| search(key, code) }
+          code_or_list.map { |code| search!(key, code) }
         else # String
           raise 'The locale code should not contain spaces. Did you accidentally use `%[]` instead of `%w[]` at call site?' if code_or_list.include?(' ')
 
-          ALL_KNOWN_LOCALES.find { |locale| locale.send(key) == code_or_list } || not_found(code_or_list, key)
+          ALL_KNOWN_LOCALES.find { |locale| locale.send(key) == code_or_list } || not_found!(code_or_list, key)
         end
       end
 
-      def not_found(code, key)
+      def not_found!(code, key)
         raise "Unknown locale for #{key} code '#{code}'"
       end
     end