[Doc] Fix some method documentations

lib/cocoapods/command/spec/edit.rb

@@ -48,7 +48,14 @@ module Pod
           raise Informative, "#{ filepath } doesn't exist."
         end
 
+        # Looks up an executable in the search paths
+        #
+        # @note
         # Thank you homebrew
+        #
+        # @param [String] cmd
+        #        the executable to look up
+        #
         def which(cmd)
           dir = ENV['PATH'].split(':').find { |p| File.executable? File.join(p, cmd) }
           Pathname.new(File.join(dir, cmd)) unless dir.nil?

lib/cocoapods/config.rb

@@ -28,6 +28,11 @@ module Pod
     # Applies the given changes to the config for the duration of the given
     # block.
     #
+    # @param [Hash<#to_sym,Object>] changes
+    #        the changes to merge temporarily with the current config
+    #
+    # @yield [] is called while the changes are applied
+    #
     def with_changes(changes)
       old = {}
       changes.keys.each do |key|

lib/cocoapods/downloader/request.rb

@@ -59,6 +59,9 @@ module Pod
       # @param  [Hash<#to_s, #to_s>] params
       #         the download parameters of the pod being downloaded.
       #
+      # @param  [Specification] spec
+      #         the specification of the pod being downloaded.
+      #
       # @return [String] The slug used to store the files resulting from this
       #         download request.
       #

lib/cocoapods/external_sources.rb

@@ -8,6 +8,14 @@ module Pod
   # source.
   #
   module ExternalSources
+    # Instantiate a matching {AbstractExternalSource} for a given dependency.
+    #
+    # @param  [Dependency] dependency
+    #         the dependency
+    #
+    # @param  [String] podfile_path
+    #         @see AbstractExternalSource#podfile_path
+    #
     # @return [AbstractExternalSource] an initialized instance of the concrete
     #         external source class associated with the option specified in the
     #         hash.
@@ -26,6 +34,11 @@ module Pod
       end
     end
 
+    # Get the class to represent the defined source type of a dependency
+    #
+    # @param  [Array<Symbol>] params
+    #         the source params of the dependency
+    #
     # @return [Class]
     #
     def self.concrete_class_from_params(params)

lib/cocoapods/external_sources/abstract_external_source.rb

@@ -41,7 +41,7 @@ module Pod
 
       # Fetches the external source from the remote according to the params.
       #
-      # @param  [Sandbox] sandbox
+      # @param  [Sandbox] _sandbox
       #         the sandbox where the specification should be stored.
       #
       # @return [void]
@@ -58,6 +58,11 @@ module Pod
 
       protected
 
+      # Return the normalized path for a podspec for a relative declared path.
+      #
+      # @param  [String] declared_path
+      #         The path declared in the podfile.
+      #
       # @return [String] The uri of the podspec appending the name of the file
       #         and expanding it if necessary.
       #

lib/cocoapods/generator/copy_resources_script.rb

@@ -13,9 +13,11 @@ module Pod
       #
       attr_reader :platform
 
-      # @param  [Hash{String, Array{String}]
-      #         resources_by_config @see resources_by_config
-      # @param  [Platform] platform @see platform
+      # @param  [Hash<String, Array<String>>] resources_by_config
+      #         @see resources_by_config
+      #
+      # @param  [Platform] platform
+      #         @see platform
       #
       def initialize(resources_by_config, platform)
         @resources_by_config = resources_by_config

lib/cocoapods/generator/target_environment_header.rb

@@ -34,10 +34,7 @@ module Pod
         @specs_by_configuration = specs_by_configuration
       end
 
-      # Generates and saves the file.
-      #
-      # @param  [Pathname] pathname
-      #         The path where to save the generated file.
+      # Generates the file contents.
       #
       # @return [void]
       #

lib/cocoapods/generator/xcconfig/xcconfig_helper.rb

@@ -11,7 +11,8 @@ module Pod
         # @param  [Array<String>] strings
         #         a list of strings.
         #
-        # @param  [String] optional prefix, such as a flag or option.
+        # @param  [String] prefix
+        #         optional prefix, such as a flag or option.
         #
         # @return [String] the resulting string.
         #
@@ -20,6 +21,12 @@ module Pod
           strings.sort.map { |s| %W(          #{prefix}"#{s}"          ) }.join(' ')
         end
 
+        # Return the default linker flags
+        #
+        # @param  [Target] target
+        #         the target, which is used to check if the ARC compatibility
+        #         flag is required.
+        #
         # @return [String] the default linker flags. `-ObjC` is always included
         #         while `-fobjc-arc` is included only if requested in the
         #         Podfile.
@@ -35,7 +42,7 @@ module Pod
 
         # Configures the given Xcconfig
         #
-        # @param  [PodTarget] pod_target
+        # @param  [PodTarget] target
         #         The pod target, which holds the list of +Spec::FileAccessor+.
         #
         # @param  [Xcodeproj::Config] xcconfig

lib/cocoapods/hooks/pod_representation.rb

@@ -11,35 +11,35 @@ module Pod
     # Stores the information of the Installer for the hooks
     #
     class PodRepresentation
-      # @return [String]
+      # @return [String] the name of the pod
       #
       attr_accessor :name
 
-      # @return [Version]
+      # @return [Version] the version
       #
       def version
         root_spec.version
       end
 
-      # @return [Specification]
+      # @return [Specification] the root spec
       #
       def root_spec
         file_accessors.first.spec.root
       end
 
-      # @return [Array<Specification>]
+      # @return [Array<Specification>] the specs
       #
       def specs
         file_accessors.map(&:spec).uniq
       end
 
-      # @return [Pathname]
+      # @return [Pathname] the root path
       #
       def root
         file_accessors.first.path_list.root
       end
 
-      # @return [Array<Pathname>]
+      # @return [Array<Pathname>] the source files
       #
       def source_files
         file_accessors.map(&:source_files).flatten.uniq

lib/cocoapods/installer.rb

@@ -172,6 +172,8 @@ module Pod
 
     # @!group Installation steps
 
+    # Performs the analysis.
+    #
     # @return [void]
     #
     # @note   The warning about the version of the Lockfile doesn't use the
@@ -707,18 +709,20 @@ module Pod
 
     # @!group Hooks Data
 
+    # Creates a hook representation for this installer.
+    #
     # @return [InstallerRepresentation]
     #
     def installer_rep
       Hooks::InstallerRepresentation.new(self)
     end
 
-    # @return [PodRepresentation] The hook representation of a Pod.
+    # Creates a hook representation for a Pod.
     #
     # @param  [String] pod
     #         The name of the pod.
     #
-    # @return [PodRepresentation] The pod representation.
+    # @return [PodRepresentation]
     #
     def pod_rep(pod)
       all_file_accessors = pod_targets.map(&:file_accessors).flatten.compact
@@ -726,18 +730,27 @@ module Pod
       Hooks::PodRepresentation.new(pod, file_accessors)
     end
 
+    # Creates a hook representation for a given aggregate target.
+    #
+    # @param  [AggregateTarget] aggregate_target
+    #         the aggregate target
+    #
     # @return [LibraryRepresentation]
     #
     def library_rep(aggregate_target)
       Hooks::LibraryRepresentation.new(sandbox, aggregate_target)
     end
 
+    # Creates hook representations for all aggregate targets.
+    #
     # @return [Array<LibraryRepresentation>]
     #
     def library_reps
       @library_reps ||= aggregate_targets.map { |lib| library_rep(lib) }
     end
 
+    # Creates hook representations for all #root_specs.
+    #
     # @return [Array<PodRepresentation>]
     #
     def pod_reps

lib/cocoapods/installer/analyzer.rb

@@ -44,6 +44,9 @@ module Pod
       # compute which specification should be installed. The manifest of the
       # sandbox returns which specifications are installed.
       #
+      # @param  [Bool] allow_fetches
+      #         whether external sources may be fetched
+      #
       # @return [AnalysisResult]
       #
       def analyze(allow_fetches = true)
@@ -72,6 +75,9 @@ module Pod
         podfile_needs_install?(analysis_result) || sandbox_needs_install?(analysis_result)
       end
 
+      # @param  [AnalysisResult] analysis_result
+      #         the analysis result to check for changes
+      #
       # @return [Bool] Whether the podfile has changes respect to the lockfile.
       #
       def podfile_needs_install?(analysis_result)
@@ -80,6 +86,9 @@ module Pod
         !needing_install.empty?
       end
 
+      # @param  [AnalysisResult] analysis_result
+      #         the analysis result to check for changes
+      #
       # @return [Bool] Whether the sandbox is in synch with the lockfile.
       #
       def sandbox_needs_install?(analysis_result)
@@ -804,10 +813,10 @@ module Pod
 
         # Adds the name of a Pod to the give state.
         #
-        # @param  [String]
+        # @param  [String] name
         #         the name of the Pod.
         #
-        # @param  [Symbol]
+        # @param  [Symbol] state
         #         the state of the Pod.
         #
         # @return [void]

lib/cocoapods/installer/analyzer/sandbox_analyzer.rb

@@ -66,7 +66,7 @@ module Pod
         # Performs the analysis to the detect the state of the sandbox respect
         # to the resolved specifications.
         #
-        # @return [SpecsState] the state of the sandbox.
+        # @return [void]
         #
         def analyze
           state = SpecsState.new

lib/cocoapods/installer/hooks_context.rb

@@ -13,6 +13,15 @@ module Pod
       #
       attr_accessor :umbrella_targets
 
+      # Generate a {HooksContext}.
+      #
+      # @param  [Sandbox] sandbox
+      #         The sandbox
+      #
+      # @param  [Array<AggregateTarget>] aggregate_targets
+      #         The aggregate targets, which will been presented by an adequate
+      #         {UmbrellaTargetDescription} in the generated context.
+      #
       # @return [HooksContext] Convenience class method to generate the
       #         static context.
       #

lib/cocoapods/installer/migrator.rb

@@ -8,7 +8,8 @@ module Pod
       class << self
         # Performs the migration.
         #
-        # @param  [Sandbox] The sandbox which should be migrated.
+        # @param  [Sandbox] sandbox
+        #         The sandbox which should be migrated.
         #
         def migrate(sandbox)
           if sandbox.manifest
@@ -21,6 +22,8 @@ module Pod
 
         # Migrates from CocoaPods versions previous to 0.34.
         #
+        # @param [Sandbox] sandbox
+        #
         def migrate_to_0_34(sandbox)
           UI.message('Migrating to CocoaPods 0.34') do
             delete(sandbox.root + 'Headers')
@@ -49,6 +52,8 @@ module Pod
 
         # Migrates from CocoaPods versions prior to 0.36.
         #
+        # @param [Sandbox] sandbox
+        #
         def migrate_to_0_36(sandbox)
           UI.message('Migrating to CocoaPods 0.36') do
             move(sandbox.root + 'Headers/Build', sandbox.root + 'Headers/Private')
@@ -69,6 +74,16 @@ module Pod
 
         # @!group Private helpers
 
+        # Check whether a migration is required
+        #
+        # @param [#to_s] target_version
+        #        See Version#new.
+        #
+        # @param [Sandbox] sandbox
+        #        The sandbox
+        #
+        # @return [void]
+        #
         def installation_minor?(target_version, sandbox)
           sandbox.manifest.cocoapods_version < Version.new(target_version)
         end
@@ -79,6 +94,8 @@ module Pod
         # @path [#to_s] path
         #       The path.
         #
+        # @return [void]
+        #
         def make_path(path)
           return if path.exist?
           UI.message "- Making path #{UI.path(path)}" do
@@ -94,6 +111,8 @@ module Pod
         # @path [#to_s] destination
         #       The destination path.
         #
+        # @return [void]
+        #
         def move(source, destination)
           return unless source.exist?
           make_path(destination.dirname)
@@ -108,6 +127,8 @@ module Pod
         # @path [#to_s] path
         #       The path.
         #
+        # @return [void]
+        #
         def delete(path)
           return unless path.exist?
           UI.message "- Deleting #{UI.path(path)}" do

lib/cocoapods/installer/pod_source_installer.rb

@@ -8,7 +8,7 @@ module Pod
     # @note This class needs to consider all the activated specs of a Pod.
     #
     class PodSourceInstaller
-      # @return [Sandbox]
+      # @return [Sandbox] The installation target.
       #
       attr_reader :sandbox
 
@@ -68,7 +68,7 @@ module Pod
         lock_installation unless local?
       end
 
-      # @return [Hash]
+      # @return [Hash] @see Downloader#checkout_options
       #
       attr_reader :specific_source
 

lib/cocoapods/installer/user_project_integrator/target_integrator.rb

@@ -257,6 +257,8 @@ module Pod
         # Read the project from the disk to ensure that it is up to date as
         # other TargetIntegrators might have modified it.
         #
+        # @return [Project]
+        #
         def user_project
           @user_project ||= Xcodeproj::Project.open(target.user_project_path)
         end

lib/cocoapods/open_uri.rb

@@ -16,6 +16,14 @@ module OpenURI
   # (RFC 2109 4.3.1, RFC 2965 3.3, RFC 2616 15.1.3)
   # However this is ad hoc.  It should be extensible/configurable.
   #
+  # @param [URI::Generic] uri1
+  #        the origin uri from where the redirect origins
+  #
+  # @param [URI::Generic] uri2
+  #        the target uri where to where the redirect points to
+  #
+  # @return [Bool]
+  #
   def self.redirectable?(uri1, uri2)
     uri1.scheme.downcase == uri2.scheme.downcase ||
       (/\A(?:http|ftp)\z/i =~ uri1.scheme && /\A(?:https?|ftp)\z/i =~ uri2.scheme)

lib/cocoapods/sandbox.rb

@@ -246,6 +246,8 @@ module Pod
     #         The contents of the specification (String) or the path to a
     #         podspec file (Pathname).
     #
+    # @return [void]
+    #
     # @todo   Store all the specifications (including those not originating
     #         from external sources) so users can check them.
     #

lib/cocoapods/sandbox/headers_store.rb

@@ -56,19 +56,19 @@ module Pod
 
       # @!group Adding headers
 
-      # Adds a header to the directory.
+      # Adds headers to the directory.
       #
-      # @param  [Pathname] namespace_path
+      # @param  [Pathname] namespace
       #         the path where the header file should be stored relative to the
       #         headers directory.
       #
-      # @param  [Pathname] relative_header_path
+      # @param  [Array<Pathname>] relative_header_paths
       #         the path of the header file relative to the Pods project
       #         (`PODS_ROOT` variable of the xcconfigs).
       #
       # @note   This method adds the files to the search paths.
       #
-      # @return [Pathname]
+      # @return [Array<Pathname>]
       #
       def add_files(namespace, relative_header_paths, platform)
         add_search_path(namespace, platform)

lib/cocoapods/sandbox/path_list.rb

@@ -61,24 +61,41 @@ module Pod
 
       # @!group Globbing
 
-      # @return [Array<Pathname>] Similar to {glob} but returns the absolute
-      #         paths.
+      # Similar to {glob} but returns the absolute paths.
+      #
+      # @param  [String,Array<String>] patterns
+      #         @see #relative_glob
+      #
+      # @param  [Hash] options
+      #         @see #relative_glob
+      #
+      # @return [Array<Pathname>]
       #
       def glob(patterns, options = {})
         relative_glob(patterns, options).map { |p| root + p }
       end
 
-      # @return [Array<Pathname>] The list of relative paths that are case
-      #         insensitively matched by a given pattern. This method emulates
-      #         {Dir#glob} with the {File::FNM_CASEFOLD} option.
+      # The list of relative paths that are case insensitively matched by a
+      # given pattern. This method emulates {Dir#glob} with the
+      # {File::FNM_CASEFOLD} option.
       #
       # @param  [String,Array<String>] patterns
       #         A single {Dir#glob} like pattern, or a list of patterns.
       #
-      # @param  [String] dir_pattern
+      # @param  [Hash] options
+      #
+      # @option options [String] :dir_pattern
       #         An optional pattern to append to a pattern, if it is the path
       #         to a directory.
       #
+      # @option options [Array<String>] :exclude_patterns
+      #         Exclude specific paths given by those patterns.
+      #
+      # @option options [Array<String>] :include_dirs
+      #         Additional paths to take into account for matching.
+      #
+      # @return [Array<Pathname>]
+      #
       def relative_glob(patterns, options = {})
         return [] if patterns.empty?
 

lib/cocoapods/sources_manager.rb

@@ -195,7 +195,9 @@ module Pod
       # Updates the local clone of the spec-repo with the given name or of all
       # the git repos if the name is omitted.
       #
-      # @param  [String] name
+      # @param  [String] source_name
+      #
+      # @param  [Bool] show_output
       #
       # @return [void]
       #

lib/cocoapods/target/aggregate_target.rb

@@ -51,8 +51,12 @@ module Pod
     #
     attr_accessor :user_target_uuids
 
-    # @return [Array<PBXNativeTarget>] The list of all the user targets that
-    #         will be integrated by this target.
+    # List all user targets that will be integrated by this #target.
+    #
+    # @param  [Xcodeproj::Project] project
+    #         The project to search for the user targets
+    #
+    # @return [Array<PBXNativeTarget>]
     #
     def user_targets(project = nil)
       return [] unless user_project_path

lib/cocoapods/user_interface.rb

@@ -37,6 +37,16 @@ module Pod
       # @todo Refactor to title (for always visible titles like search)
       #       and sections (titles that represent collapsible sections).
       #
+      # @param [String] title
+      #        The title to print
+      #
+      # @param [String] verbose_prefix
+      #        See #message
+      #
+      # @param [FixNum] relative_indentation
+      #        The indentation level relative to the current,
+      #        when the message is printed.
+      #
       def section(title, verbose_prefix = '', relative_indentation = 0)
         if config.verbose?
           title(title, verbose_prefix, relative_indentation)
@@ -74,6 +84,16 @@ module Pod
 
       # A title opposed to a section is always visible
       #
+      # @param [String] title
+      #        The title to print
+      #
+      # @param [String] verbose_prefix
+      #        See #message
+      #
+      # @param [FixNum] relative_indentation
+      #        The indentation level relative to the current,
+      #        when the message is printed.
+      #
       def title(title, verbose_prefix = '', relative_indentation = 2)
         if @treat_titles_as_messages
           message(title, verbose_prefix)
@@ -102,6 +122,16 @@ module Pod
       #
       # @todo Clean interface.
       #
+      # @param [String] message
+      #        The message to print.
+      #
+      # @param [String] verbose_prefix
+      #        See #message
+      #
+      # @param [FixNum] relative_indentation
+      #        The indentation level relative to the current,
+      #        when the message is printed.
+      #
       def message(message, verbose_prefix = '', relative_indentation = 2)
         message = verbose_prefix + message if config.verbose?
         puts_indented message if config.verbose?
@@ -117,6 +147,9 @@ module Pod
       #
       # Any title printed in the optional block is treated as a message.
       #
+      # @param [String] message
+      #        The message to print.
+      #
       def info(message)
         indentation = config.verbose? ? self.indentation_level : 0
         indented = wrap_string(message, indentation)
@@ -143,6 +176,9 @@ module Pod
       # The returned path is quoted. If the argument is nil it returns the
       # empty string.
       #
+      # @param [#to_str] pathname
+      #        The path to print.
+      #
       def path(pathname)
         if pathname
           from_path = config.podfile_path.dirname if config.podfile_path
@@ -156,6 +192,12 @@ module Pod
 
       # Prints the textual representation of a given set.
       #
+      # @param  [Set] set
+      #         the set that should be presented.
+      #
+      # @param  [Symbol] mode
+      #         the presentation mode, either `:normal` or `:name_and_version`.
+      #
       def pod(set, mode = :normal)
         if mode == :name_and_version
           puts_indented "#{set.name} #{set.versions.first.version}"
@@ -190,6 +232,15 @@ module Pod
 
       # Prints a message with a label.
       #
+      # @param [String] label
+      #        The label to print.
+      #
+      # @param [#to_s] value
+      #        The value to print.
+      #
+      # @param [FixNum] justification
+      #        The justification of the label.
+      #
       def labeled(label, value, justification = 12)
         if value
           title = "- #{label}:"
@@ -208,6 +259,9 @@ module Pod
       # Prints a message respecting the current indentation level and
       # wrapping it to the terminal width if necessary.
       #
+      # @param [String] message
+      #        The message to print.
+      #
       def puts_indented(message = '')
         indented = wrap_string(message, self.indentation_level)
         puts(indented)
@@ -238,12 +292,18 @@ module Pod
 
       # prints a message followed by a new line unless config is silent.
       #
+      # @param [String] message
+      #        The message to print.
+      #
       def puts(message = '')
         STDOUT.puts(message) unless config.silent?
       end
 
       # prints a message followed by a new line unless config is silent.
       #
+      # @param [String] message
+      #        The message to print.
+      #
       def print(message)
         STDOUT.print(message) unless config.silent?
       end
@@ -259,6 +319,8 @@ module Pod
       #
       # @param [String]  message The message to print.
       # @param [Array]   actions The actions that the user should take.
+      # @param [Bool]    verbose_only
+      #        Restrict the appearance of the warning to verbose mode only
       #
       # return [void]
       #

lib/cocoapods/validator.rb

@@ -167,7 +167,8 @@ module Pod
       result_type != :error && (result_type != :warning || allow_warnings)
     end
 
-    # @return [Symbol]
+    # @return [Symbol] The type, which should been used to display the result.
+    #         One of: `:error`, `:warning`, `:note`.
     #
     def result_type
       types = results.map(&:type).uniq
@@ -177,7 +178,8 @@ module Pod
       end
     end
 
-    # @return [Symbol]
+    # @return [Symbol] The color, which should been used to display the result.
+    #         One of: `:green`, `:yellow`, `:red`.
     #
     def result_color
       case result_type