Clean up some comments and minor house keeping

lib/cocoapods/installer/analyzer.rb

@@ -214,11 +214,24 @@ module Pod
         end
       end
 
-      # If modifications to the sandbox are allowed external sources are
-      # fetched. In update mode all the external sources are refreshed while in
-      # normal mode they refreshed only if added or changed in the Podfile.
+      # Fetches the podspecs of external sources if modifications to the
+      # sandbox are allowed.
       #
-      # TODO Specs, comments, and fix UI
+      # @note   In update mode all the external sources are refreshed while in
+      #         normal mode they are refreshed only if added or changed in the
+      #         Podfile. Moreover, in normal specifications for unchanged Pods
+      #         which are missing or are generated from an local source are
+      #         fetched as well.
+      #
+      # @note   It is possible to perform this step before the resolution
+      #         process because external sources identify a single specific
+      #         version (checkout). If the other dependencies are not
+      #         compatible with the version reported by the podspec of the
+      #         external source the resolver will raise.
+      #
+      # @return [void]
+      #
+      # TODO    Specs
       #
       def fetch_external_sources
         return unless allow_pre_downloads?

lib/cocoapods/validator.rb

@@ -101,7 +101,9 @@ module Pod
 
     # @!group Configuration
 
-    # @return [Boolean] TODO
+    # @return [Bool] Whether the validator should print the results of the
+    #         validation. This is useful for clients which want to customize
+    #         output.
     #
     attr_accessor :disable_ui_output
 
@@ -127,7 +129,8 @@ module Pod
     attr_writer :local
     def local?; @local; end
 
-    # @return [Boolean] TODO
+    # @return [Bool] Whether the validator should fail only on errors or also
+    #         on warnings.
     #
     attr_accessor :only_errors
 
@@ -221,7 +224,6 @@ module Pod
     end
 
     def tear_down_validation_environment
-      # TODO
       validation_dir.rmtree unless no_clean
       Config.instance = @original_config
     end

spec/functional/command/spec_spec.rb

@@ -120,7 +120,7 @@ module Pod
         end
       end
 
-      # TODO VCR is required in CocoaPods only for this test.
+      # @todo VCR is required in CocoaPods only for this test.
       #
       # it "lints a remote podspec" do
       #   Dir.chdir(fixture('spec-repos') + 'master/JSONKit/1.4/') do

spec/integration_2.rb

@@ -88,8 +88,6 @@ end
 #         environment.
 #
 def launch_binary(arguments, folder)
-  # TODO CP 0.16 doesn't offer the possibility to skip just the installation
-  # of the docs.
   command = "#{POD_BINARY} #{arguments} --verbose --no-color 2>&1"
   Dir.chdir(TMP_DIR + folder) do
     output = `#{command}`
@@ -336,19 +334,19 @@ describe "Integration take 2" do
       check "install --no-update --no-doc", "install_podspec"
     end
 
-    # TODO add tests for all the hooks API
+    # @todo add tests for all the hooks API
     #
     describe "Runs the Podfile callbacks" do
       check "install --no-update --no-doc", "install_podfile_callbacks"
     end
 
-    # TODO add tests for all the hooks API
+    # @todo add tests for all the hooks API
     #
     describe "Runs the specification callbacks" do
       check "install --no-update --no-doc", "install_spec_callbacks"
     end
 
-    # TODO: requires CocoaPods 0.17
+    # @todo requires CocoaPods 0.17
     #
     # describe "Generates the documentation of Pod during installation" do
     #   check "install --no-update --no-doc", "install_docs"

spec/spec_helper.rb

@@ -92,12 +92,6 @@ def fixture_file_accessor(name, platform = :ios)
   Pod::Sandbox::FileAccessor.new(path_list, spec.consumer(platform))
 end
 
-# TODO This should not be needed anymore
-def copy_fixture_to_pod(name, pod)
-  path = SpecHelper::Fixture.fixture(name)
-  FileUtils.cp_r(path, pod.root)
-end
-
 #-----------------------------------------------------------------------------#
 
 SpecHelper::Fixture.fixture('banana-lib') # ensure it exists

spec/spec_helper/command.rb

@@ -12,7 +12,7 @@ module SpecHelper
     def run_command(*args)
       Dir.chdir(SpecHelper.temporary_directory) do
         Pod::UI.output = ''
-        # TODO: remove this once all cocoapods has
+        # @todo Remove this once all cocoapods has
         # been converted to use the UI.puts
         config_silent = config.silent?
         config.silent = false

spec/spec_helper/user_interface.rb

@@ -10,6 +10,9 @@ module Pod
       attr_accessor :output
       attr_accessor :warnings
 
+      # @todo Allow to specify whether the text should be wrapped with an
+      #       environment variable and remove the new feed replacement.
+
       def puts(message = '')
         # Wrapping can bite in tests.
         @output << "#{message}".gsub(/\n/,'')