Merge pull request #3544 from CocoaPods/mr-doc-improvements

[Doc] Improvements and Rake task to lint with inch

Gemfile

@@ -30,6 +30,7 @@ group :development do
   gem 'mocha-on-bacon'
   gem 'prettybacon'
   gem 'webmock'
+  gem 'inch'
 
   # Integration tests
   gem 'diffy'

Gemfile.lock

@@ -98,6 +98,7 @@ GEM
       colored (~> 1.2)
       diffy
     cocoapods-dependencies (0.4.0)
+    coderay (1.1.0)
     colored (1.2)
     crack (0.4.2)
       safe_yaml (~> 1.0.0)
@@ -106,6 +107,11 @@ GEM
     ffi (1.9.6)
     fuzzy_match (2.0.4)
     i18n (0.7.0)
+    inch (0.5.10)
+      pry
+      sparkr (>= 0.2.0)
+      term-ansicolor
+      yard (~> 0.8.7.5)
     json (1.7.7)
     kicker (3.0.0)
       listen (~> 1.3.0)
@@ -115,6 +121,7 @@ GEM
       rb-inotify (>= 0.9)
       rb-kqueue (>= 0.2)
     metaclass (0.0.4)
+    method_source (0.8.2)
     minitest (5.6.1)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
@@ -128,6 +135,10 @@ GEM
     powerpack (0.1.0)
     prettybacon (0.0.2)
       bacon (~> 1.2)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
     rainbow (2.0.0)
     rake (10.4.2)
     rb-fsevent (0.9.4)
@@ -144,12 +155,18 @@ GEM
     ruby-prof (0.15.2)
     ruby-progressbar (1.7.1)
     safe_yaml (1.0.4)
+    slop (3.6.0)
+    sparkr (0.4.1)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
     thread_safe (0.3.5)
+    tins (1.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     webmock (1.20.4)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -168,6 +185,7 @@ DEPENDENCIES
   cocoapods-trunk!
   cocoapods-try!
   diffy
+  inch
   json (= 1.7.7)
   kicker
   mocha

Rakefile

@@ -141,6 +141,9 @@ begin
 
       title 'Running RuboCop'
       Rake::Task['rubocop'].invoke
+
+      title 'Running Inch'
+      Rake::Task['inch:spec'].invoke
     end
 
     namespace :fixture_tarballs do
@@ -295,6 +298,60 @@ begin
     sh 'bundle exec rubocop lib spec Rakefile'
   end
 
+  #-- Inch -------------------------------------------------------------------#
+
+  namespace :inch do
+    desc 'Lint the completeness of the documentation with Inch'
+    task :spec do
+      require 'inch'
+      require 'inch/cli'
+
+      puts 'Parse docs …'
+      YARD::Parser::SourceParser.before_parse_file do |_|
+        print green('.') # Visualize progress
+      end
+
+      class ProgressEnumerable
+        include Enumerable
+
+        def initialize(array)
+          @array = array
+        end
+
+        def each
+          @array.each do |e|
+            print '.'
+            yield e
+          end
+        end
+      end
+
+      Inch::Codebase::Objects.class_eval do
+        alias_method :old_init, :initialize
+        def initialize(language, objects)
+          puts "\n\nEvaluating …"
+          old_init(language, ProgressEnumerable.new(objects))
+        end
+      end
+
+      codebase = Inch::Codebase.parse(Dir.pwd, Inch::Config.codebase)
+      context = Inch::API::List.new(codebase, {})
+      options = Inch::CLI::Command::Options::List.new
+      options.show_all = true
+      options.ui = Inch::Utils::UI.new
+      failing_grade_symbols = [:B, :C] # add :U for undocumented
+      failing_grade_list = context.grade_lists.select { |g| failing_grade_symbols.include?(g.to_sym) }
+      Inch::CLI::Command::Output::List.new(options, context.objects, failing_grade_list)
+      puts
+      if context.objects.any? { |o| failing_grade_symbols.include?(o.grade.to_sym) }
+        puts red('✗ Lint of Documentation failed: Please improve above suggestions.')
+        exit 1
+      else
+        puts green('✓ Nothing to improve detected.')
+      end
+    end
+  end
+
 rescue LoadError, NameError => e
   $stderr.puts "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \
@@ -333,6 +390,10 @@ def title(title)
   puts
 end
 
+def green(string)
+  "\033[0;32m#{string}\e[0m"
+end
+
 def red(string)
   "\033[0;31m#{string}\e[0m"
 end

lib/cocoapods/command/outdated.rb

@@ -17,6 +17,8 @@ module Pod
         super
       end
 
+      # Run the command
+      #
       # @todo the command report new dependencies added to the Podfile as
       #       updates.
       #

lib/cocoapods/command/repo/lint.rb

@@ -24,6 +24,8 @@ module Pod
           super
         end
 
+        # Run the command
+        #
         # @todo Part of this logic needs to be ported to cocoapods-core so web
         #       services can validate the repo.
         #

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/cache.rb

@@ -12,6 +12,8 @@ module Pod
       #
       attr_reader :root
 
+      # Initialize a new instance
+      #
       # @param  [Pathname,String] root
       #         see {#root}
       #

lib/cocoapods/downloader/request.rb

@@ -28,6 +28,8 @@ module Pod
       attr_reader :head
       alias_method :head?, :head
 
+      # Initialize a new instance
+      #
       # @param  [Specification,Nil] spec
       #         see {#spec}
       #
@@ -59,6 +61,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/executable.rb

@@ -101,6 +101,8 @@ module Pod
       #
       attr_accessor :io
 
+      # Init a new Indenter
+      #
       # @param [IO] io @see io
       #
       def initialize(io = nil)

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

@@ -17,6 +17,8 @@ module Pod
       #
       attr_reader :podfile_path
 
+      # Initialize a new instance
+      #
       # @param [String] name @see name
       # @param [Hash] params @see params
       # @param [String] podfile_path @see podfile_path
@@ -41,7 +43,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 +60,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,13 @@ module Pod
       #
       attr_reader :platform
 
-      # @param  [Hash{String, Array{String}]
-      #         resources_by_config @see resources_by_config
-      # @param  [Platform] platform @see platform
+      # Initialize a new instance
+      #
+      # @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/header.rb

@@ -19,6 +19,8 @@ module Pod
       #
       attr_accessor :module_imports
 
+      # Initialize a new instance
+      #
       # @param  [Symbol] platform
       #         @see platform
       #

lib/cocoapods/generator/info_plist_file.rb

@@ -9,6 +9,8 @@ module Pod
       #
       attr_reader :target
 
+      # Initialize a new instance
+      #
       # @param  [Target] target @see target
       #
       def initialize(target)

lib/cocoapods/generator/module_map.rb

@@ -6,15 +6,17 @@ module Pod
     # with existing headers of the podspec.
     #
     class ModuleMap
-      # @return [Target] the target represented by this Info.plist.
+      # @return [PodTarget] the target represented by this Info.plist.
       #
       attr_reader :target
 
-      # @return [Array] the private headers of the module
+      # @return [Array<#to_s>] the private headers of the module
       #
       attr_accessor :private_headers
 
-      # @param  [Target] target @see target
+      # Initialize a new instance
+      #
+      # @param  [PodTarget] target @see target
       #
       def initialize(target)
         @target = target

lib/cocoapods/generator/prefix_header.rb

@@ -12,6 +12,8 @@ module Pod
       #
       attr_reader :file_accessors
 
+      # Initialize a new instance
+      #
       # @param  [Array<FileAccessor>] file_accessors
       #         @see file_accessors
       #

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/umbrella_header.rb

@@ -12,6 +12,8 @@ module Pod
       #         the target, which provides the product name
       attr_reader :target
 
+      # Initialize a new instance
+      #
       # @param  [Target] target
       #         @see target
       #

lib/cocoapods/generator/xcconfig/aggregate_xcconfig.rb

@@ -8,6 +8,8 @@ module Pod
         #
         attr_reader :target
 
+        # Initialize a new instance
+        #
         # @param  [Target] target @see target
         #
         # @param  [String] configuration_name
@@ -26,7 +28,7 @@ module Pod
         # Generates and saves the xcconfig to the given path.
         #
         # @param  [Pathname] path
-        #         the path where the prefix header should be stored.
+        #         the path where the xcconfig should be stored.
         #
         # @return [void]
         #

lib/cocoapods/generator/xcconfig/private_pod_xcconfig.rb

@@ -17,6 +17,8 @@ module Pod
         #
         attr_reader :public_xcconfig
 
+        # Initialize a new instance
+        #
         # @param  [Target] target @see target
         # @param  [Xcodeproj::Config] public_xcconfig @see public_xcconfig
         #

lib/cocoapods/generator/xcconfig/public_pod_xcconfig.rb

@@ -13,6 +13,8 @@ module Pod
         #
         attr_reader :target
 
+        # Initialize a new instance
+        #
         # @param  [Target] target @see target
         #
         def initialize(target)

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
@@ -70,10 +77,10 @@ module Pod
           add_developers_frameworks_if_needed(xcconfig, consumer.platform_name)
         end
 
-        # Configures the given Xcconfig with the the build settings for the given
+        # Configures the given Xcconfig with the build settings for the given
         # framework path.
         #
-        # @param  [Pathanme] framework_path
+        # @param  [Pathname] framework_path
         #         The path of the framework.
         #
         # @param  [Xcodeproj::Config] xcconfig
@@ -92,11 +99,11 @@ module Pod
           xcconfig.merge!(build_settings)
         end
 
-        # Configures the given Xcconfig with the the build settings for the given
+        # Configures the given Xcconfig with the build settings for the given
         # library path.
         #
-        # @param  [Pathanme] framework_path
-        #         The path of the framework.
+        # @param  [Pathname] library_path
+        #         The path of the library.
         #
         # @param  [Xcodeproj::Config] xcconfig
         #         The xcconfig to edit.

lib/cocoapods/hooks/installer_representation.rb

@@ -119,6 +119,8 @@ module Pod
 
       # @!group Private implementation
 
+      # Initialize a new instance
+      #
       # @param [Installer] installer @see installer
       #
       def initialize(installer)

lib/cocoapods/hooks/library_representation.rb

@@ -61,7 +61,7 @@ module Pod
       #
       attr_reader :sandbox
 
-      # @return [Library] The library whose target needs to be generated.
+      # @return [Target] The library whose target needs to be generated.
       #
       attr_reader :library
 
@@ -76,8 +76,10 @@ module Pod
 
       # @!group Private implementation
 
+      # Initialize a new instance
+      #
       # @param [Sandbox] sandbox @see sandbox
-      # @param [Library] library @see library
+      # @param [Target]  library @see library
       #
       def initialize(sandbox, library)
         @sandbox = sandbox

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/hooks_manager.rb

@@ -34,6 +34,8 @@ module Pod
       #
       attr_reader :block
 
+      # Initialize a new instance
+      #
       # @param  [String] name        @see {#name}.
       #
       # @param  [String] plugin_name @see {#plugin_name}.

lib/cocoapods/installer.rb

@@ -55,6 +55,8 @@ module Pod
     #
     attr_reader :lockfile
 
+    # Initialize a new instance
+    #
     # @param  [Sandbox]  sandbox     @see sandbox
     # @param  [Podfile]  podfile     @see podfile
     # @param  [Lockfile] lockfile    @see lockfile
@@ -172,6 +174,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 +711,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 +732,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

@@ -24,6 +24,8 @@ module Pod
       #
       attr_reader :lockfile
 
+      # Initialize a new instance
+      #
       # @param  [Sandbox]  sandbox     @see sandbox
       # @param  [Podfile]  podfile     @see podfile
       # @param  [Lockfile] lockfile    @see lockfile
@@ -44,6 +46,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 +77,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 +88,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)
@@ -181,7 +192,7 @@ module Pod
 
       # Creates the models that represent the libraries generated by CocoaPods.
       #
-      # @return [Array<Libraries>] the generated libraries.
+      # @return [Array<Target>] the generated libraries.
       #
       def generate_targets
         targets = []
@@ -757,6 +768,8 @@ module Pod
       #       subspecs are added instead of the name of the Pods.
       #
       class SpecsState
+        # Initialize a new instance
+        #
         # @param  [Hash{Symbol=>String}] pods_by_state
         #         The name of the pods grouped by their state
         #         (`:added`, `:removed`, `:changed` or `:unchanged`).
@@ -804,10 +817,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

@@ -51,6 +51,8 @@ module Pod
         #
         attr_reader :lockfile
 
+        # Init a new SandboxAnalyzer
+        #
         # @param [Sandbox] sandbox @see sandbox
         # @param [Array<Specifications>] specs @see specs
         # @param [Bool] update_mode @see update_mode
@@ -66,7 +68,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/file_references_installer.rb

@@ -16,6 +16,8 @@ module Pod
       #
       attr_reader :pods_project
 
+      # Initialize a new instance
+      #
       # @param [Sandbox] sandbox @see sandbox
       # @param [Array<PodTarget>] libraries @see libraries
       # @param [Project] libraries @see libraries
@@ -153,7 +155,7 @@ module Pod
       #         The key of the group of the Pods project.
       #
       # @param  [Bool] reflect_file_system_structure_for_development
-      #         Wether organizing the a local pod's files in subgroups inside
+      #         Whether organizing a local pod's files in subgroups inside
       #         the pod's group is allowed.
       #
       # @return [void]

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
 
@@ -17,6 +17,8 @@ module Pod
       #
       attr_reader :specs_by_platform
 
+      # Initialize a new instance
+      #
       # @param [Sandbox] sandbox @see sandbox
       # @param [Hash{Symbol=>Array}] specs_by_platform @see specs_by_platform
       #
@@ -68,7 +70,7 @@ module Pod
         lock_installation unless local?
       end
 
-      # @return [Hash]
+      # @return [Hash] @see Downloader#checkout_options
       #
       attr_reader :specific_source
 

lib/cocoapods/installer/pod_source_preparer.rb

@@ -12,6 +12,8 @@ module Pod
       #
       attr_reader :path
 
+      # Initialize a new instance
+      #
       # @param [Specification] spec the root specification of the Pod.
       # @param [Pathname] path the folder where the source of the Pod is located.
       #

lib/cocoapods/installer/user_project_integrator.rb

@@ -33,14 +33,16 @@ module Pod
       #
       attr_reader :installation_root
 
-      # @return [Array<Target>] the targets represented in the Podfile.
+      # @return [Array<AggregateTarget>] the targets represented in the Podfile.
       #
       attr_reader :targets
 
+      # Init a new UserProjectIntegrator
+      #
       # @param  [Podfile]  podfile @see #podfile
       # @param  [Sandbox]  sandbox @see #sandbox
       # @param  [Pathname] installation_root @see #installation_root
-      # @param  [Library]  libraries @see #libraries
+      # @param  [Array<AggregateTarget>]  targets @see #targets
       #
       # @todo   Too many initialization arguments
       #

lib/cocoapods/installer/user_project_integrator/target_integrator.rb

@@ -14,11 +14,13 @@ module Pod
         #
         EMBED_FRAMEWORK_TARGET_TYPES = [:application, :unit_test_bundle].freeze
 
-        # @return [Target] the target that should be integrated.
+        # @return [AggregateTarget] the target that should be integrated.
         #
         attr_reader :target
 
-        # @param  [Target] target @see #target_definition
+        # Init a new TargetIntegrator
+        #
+        # @param  [AggregateTarget] target @see #target
         #
         def initialize(target)
           @target = target
@@ -257,6 +259,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/project.rb

@@ -7,6 +7,8 @@ module Pod
   # through the installation process.
   #
   class Project < Xcodeproj::Project
+    # Initialize a new instance
+    #
     # @param  [Pathname, String] path @see path
     # @param  [Bool] skip_initialization
     #         Whether the project should be initialized from scratch.
@@ -169,7 +171,7 @@ module Pod
     #         The group for the new file reference.
     #
     # @param  [Bool] reflect_file_system_structure
-    #         Wether group structure should reflect the file system structure.
+    #         Whether group structure should reflect the file system structure.
     #         If yes, where needed, intermediate groups are created, similar to
     #         how mkdir -p operates.
     #

lib/cocoapods/resolver.rb

@@ -25,6 +25,8 @@ module Pod
     #
     attr_accessor :sources
 
+    # Init a new Resolver
+    #
     # @param  [Sandbox] sandbox @see sandbox
     # @param  [Podfile] podfile @see podfile
     # @param  [Array<Dependency>] locked_dependencies @see locked_dependencies

lib/cocoapods/sandbox.rb

@@ -50,6 +50,8 @@ module Pod
     #
     attr_reader :public_headers
 
+    # Initialize a new instance
+    #
     # @param [String, Pathname] root @see root
     #
     def initialize(root)
@@ -246,6 +248,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/file_accessor.rb

@@ -27,6 +27,8 @@ module Pod
       #
       attr_reader :spec_consumer
 
+      # Initialize a new instance
+      #
       # @param [Sandbox::PathList, Pathname] path_list @see path_list
       # @param [Specification::Consumer] spec_consumer @see spec_consumer
       #
@@ -168,7 +170,7 @@ module Pod
       end
 
       # @return [Hash{String => Array<Pathname>}] A hash that describes the
-      #         resource bundles of the Pod. The keys reppresent the name of
+      #         resource bundles of the Pod. The keys represent the name of
       #         the bundle while the values the path of the resources.
       #
       def resource_bundles

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

@@ -15,6 +15,8 @@ module Pod
       #
       attr_accessor :root
 
+      # Initialize a new instance
+      #
       # @param  [Pathname] root The root of the PathList.
       #
       def initialize(root)
@@ -61,24 +63,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.rb

@@ -6,7 +6,7 @@ module Pod
   # This class is used to represent both the targets and their libraries.
   #
   class Target
-    # @return [PBXNativeTarget] the target definition of the Podfile that
+    # @return [TargetDefinition] the target definition of the Podfile that
     #         generated this target.
     #
     attr_reader :target_definition

lib/cocoapods/target/aggregate_target.rb

@@ -3,6 +3,8 @@ module Pod
   # of the single Pods. The client targets will then depend on this one.
   #
   class AggregateTarget < Target
+    # Initialize a new instance
+    #
     # @param [TargetDefinition] target_definition @see target_definition
     # @param [Sandbox] sandbox @see sandbox
     #
@@ -51,8 +53,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

@@ -16,6 +16,8 @@ module Pod
     #
     attr_reader :linter
 
+    # Initialize a new instance
+    #
     # @param  [Specification, Pathname, String] spec_or_path
     #         the Specification or the path of the `podspec` file to lint.
     #
@@ -167,7 +169,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 +180,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