Merge pull request #327 from wordpress-mobile/yard/misc-doc

Comment some functions a bit more #trivial

Author: AliSoftware

lib/fastlane/plugin/wpmreleasetoolkit/actions/android/an_localize_libs_action.rb

@@ -36,12 +36,17 @@ def self.available_options
           FastlaneCore::ConfigItem.new(key: :app_strings_path,
                                        description: 'The path of the main strings file',
                                        optional: false,
-                                       is_string: true),
+                                       type: String),
+          # The name of this parameter is a bit misleading due to legacy. In practice it's expected to be an Array of Hashes, each describing a library to merge.
+          # See `Fastlane::Helper::Android::LocalizeHelper.merge_lib`'s YARD doc for more details on the keys expected for each Hash.
           FastlaneCore::ConfigItem.new(key: :libs_strings_path,
                                        env_name: 'LOCALIZE_LIBS_STRINGS_PATH',
-                                       description: 'The list of libs to merge',
+                                       description: 'The list of libs to merge. ' \
+                                         + 'Each item in the provided array must be a Hash with the keys `:library` (The library display name),' \
+                                         + '`:strings_path` (The path to the `strings.xml` file of the library) and ' \
+                                         + '`:exclusions` (Array of string keys to exclude from merging)',
                                        optional: false,
-                                       is_string: false),
+                                       type: Array),
         ]
       end
 

lib/fastlane/plugin/wpmreleasetoolkit/actions/common/gp_downloadmetadata_action.rb

@@ -58,7 +58,7 @@ def self.available_options
                                        is_string: false),
           FastlaneCore::ConfigItem.new(key: :locales,
                                        env_name: 'FL_DOWNLOAD_METADATA_LOCALES',
-                                       description: 'The hash with the GLotPress locale and the project locale association',
+                                       description: 'The hash with the GlotPress locale and the project locale association',
                                        is_string: false),
           FastlaneCore::ConfigItem.new(key: :source_locale,
                                        env_name: 'FL_DOWNLOAD_METADATA_SOURCE_LOCALE',

lib/fastlane/plugin/wpmreleasetoolkit/helper/android/android_localize_helper.rb

@@ -92,6 +92,14 @@ def self.verify_string(main_strings, library, string_line)
           UI.user_error!("String #{string_name} [#{string_content}] was found in library #{library[:library]} but not in the main file.")
         end
 
+        # Merge strings from a library into the strings.xml of the main app
+        #
+        # @param [String] main Path to the main strings.xml file (something like `…/res/values/strings.xml`)
+        # @param [Hash] library Hash describing the library to merge. The Hash should contain the following keys:
+        #                       - `:library`: The human readable name of the library, used to display in console messages
+        #                       - `:strings_path`: The path to the strings.xml file of the library to merge into the main one
+        #                       - `:exclusions`: An array of strings keys to exclude during merge. Any of those keys from the library's `strings.xml` will be skipped and won't be merged into the main one.
+        # @return [Boolean] True if at least one string from the library has been added to (or has updated) the main strings file.
         def self.merge_lib(main, library)
           UI.message("Merging #{library[:library]} strings into #{main}")
           main_strings = File.open(main) { |f| Nokogiri::XML(f, nil, Encoding::UTF_8.to_s) }

lib/fastlane/plugin/wpmreleasetoolkit/helper/ios/ios_git_helper.rb

@@ -35,8 +35,9 @@ def self.commit_version_bump(include_deliverfile: true, include_metadata: true)
         # @env PROJECT_ROOT_FOLDER The path to the git root of the project
         # @env PROJECT_NAME The name of the directory containing the project code (especially containing the `build.gradle` file)
         #
-        # @todo Migrate the scripts, currently in each host repo and called by this method, to be helpers and actions
-        #       in the release-toolkit instead, and move this code away from `ios_git_helper`.
+        # @deprecated This method is only used by the `ios_localize_project` action, which is itself deprecated
+        #             in favor of the new `ios_generate_strings_file_from_code` action
+        # @todo [Next Major] Remove this method once we fully remove `ios_localize_project`
         #
         def self.localize_project
           Action.sh("cd #{get_from_env!(key: 'PROJECT_ROOT_FOLDER')} && ./Scripts/localize.py")