[Docs] Preliminary support for YARD.

.gitignore

@@ -18,3 +18,4 @@ spec/fixtures/integration/Headers/
 spec/fixtures/mercurial-repo/.hg/*cache
 .hg
 spec/fixtures/vcr
+.yardoc

.yardopts

+--markup markdown
+--exclude examples
+--exclude spec
+--exclude tmp

Gemfile

@@ -20,4 +20,8 @@ group :development do
   gem "webmock"
   gem "awesome_print"
   gem "pry"
+
+  gem 'yard'
+  gem 'redcarpet'
+  gem 'github-markup'
 end

Gemfile.lock

@@ -19,6 +19,7 @@ GEM
       multipart-post (~> 1.1)
     faraday_middleware (0.8.7)
       faraday (>= 0.7.4, < 0.9)
+    github-markup (0.7.2)
     hashie (1.2.0)
     json (1.7.3)
     kicker (2.5.0)
@@ -44,11 +45,13 @@ GEM
       slop (>= 2.4.4, < 3)
     rake (0.9.2.2)
     rb-fsevent (0.9.1)
+    redcarpet (2.1.1)
     slop (2.4.4)
     vcr (2.2.0)
     webmock (1.8.7)
       addressable (>= 2.2.7)
       crack (>= 0.1.7)
+    yard (0.8.2)
 
 PLATFORMS
   ruby
@@ -59,6 +62,7 @@ DEPENDENCIES
   colored
   escape
   faraday (>= 0.8.1)
+  github-markup
   json
   kicker
   mocha-on-bacon
@@ -67,6 +71,8 @@ DEPENDENCIES
   pry
   rake
   rb-fsevent
+  redcarpet
   vcr
   webmock
   xcodeproj!
+  yard

lib/cocoapods/platform.rb

 module Pod
+
+  # Describes an build envronment. It caputures information about the SDK and a deployment target.
+  #
   class Platform
+
+    # @return [Platform] Convenience method to initialize an iOS platform
+    #
     def self.ios
       new :ios
     end
 
+    # @return [Platform] Convenience method to initialize an OS X platform
+    #
     def self.osx
       new :osx
     end
 
-    attr_reader :deployment_target
-
-    ##
-    # Public: Constructs a platform from either another platform or by
+    # Constructs a platform from either another platform or by
     # specifying the symbolic name and optionally the deployment target.
     #
-    # input             - Another platform or the symbolic name of the platform.
-    # deployment_target - The optional deployment target if initalized by
-    #                     symbolic name
+    # @param [Platform, Symbol] input Another platform or a symbolic name for the platform.
+    # @param [Version, {Symbol=>Object}] deployment_target The optional deployment target if initalized by symbolic name
     #
-    # Examples
+    # Examples:
     #
+    # ```
     # Platform.new(:ios)
     # Platform.new(:ios, '4.3')
     # Platform.new(Platform.new(:ios))
+    # ```
     #
-    # Returns nothing.
-
     def initialize(input = nil, deployment_target = nil)
       if input.is_a? Platform
         @symbolic_name = input.name
@@ -39,22 +43,44 @@ module Pod
       end
     end
 
+    # @return [Symbol] The name of the SDK reppresented by the platform.
+    #
     def name
       @symbolic_name
     end
 
+    # The optional deployment target of the platform.
+    # A deployment target can be specified as a string.
+    #
+    # @return [Version]
+    attr_reader :deployment_target
+
     def deployment_target= (version)
       @deployment_target = Pod::Version.create(version)
     end
 
-    def ==(other_platform_or_symbolic_name)
-      if other_platform_or_symbolic_name.is_a?(Symbol)
-        @symbolic_name == other_platform_or_symbolic_name
+    # Checks if two platforms are the equivalent.
+    #
+    # @param [Platform, Symbol] other The other platform to check. If a symbol is
+    #                                 passed the comparison does not take into
+    #                                 account the deployment target.
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      if other.is_a?(Symbol)
+        @symbolic_name == other
       else
-        self.name == (other_platform_or_symbolic_name.name) && self.deployment_target == other_platform_or_symbolic_name.deployment_target
+        self.name == (other.name) && self.deployment_target == other.deployment_target
       end
     end
 
+    # A platfrom supports (from the point of view of a pod) another platform if they reppresent the same SDK and if the
+    # deployment target of the other is lower. If one of the platforms does not specify the deployment target, it is not taken into account.
+    #
+    # This method always returns true if one of platforms is nil.
+    #
+    # **TODO**: rename to supported_on?
     def supports?(other)
       return true if @symbolic_name.nil? || other.nil?
       os_check      = @symbolic_name == other.name
@@ -62,6 +88,10 @@ module Pod
       os_check && version_check
     end
 
+    # A string reppresentation of the Platform including the deployment target if specified.
+    #
+    # @return [String] A string reppresentation.
+    #
     def to_s
       case @symbolic_name
       when :ios
@@ -73,14 +103,21 @@ module Pod
       end
     end
 
+    # @return [Symbol] A Symbol reppresentation of the SDK.
+    #
     def to_sym
       name
     end
 
+    # A platform behaves as nil if doesn't specify an SDK.
+    # A nil platform reppresents all the available platforms.
+    #
     def nil?
       name.nil?
     end
 
+    # @return Whether the platform requires legacy architectures for iOS.
+    #
     def requires_legacy_ios_archs?
       return unless deployment_target
       (name == :ios) && (deployment_target < Pod::Version.new("4.3"))

lib/cocoapods/podfile.rb

@@ -332,12 +332,14 @@ module Pod
     # Pod::Specification is yielded to the block. This is the same class which
     # is normally used to specify a Pod.
     #
+    # ```
     #   dependency do |spec|
     #     spec.name         = 'JSONKit'
     #     spec.version      = '1.4'
     #     spec.source       = { :git => 'https://github.com/johnezang/JSONKit.git', :tag => 'v1.4' }
     #     spec.source_files = 'JSONKit.*'
     #   end
+    # ```
     #
     #
     # For more info on the definition of a Pod::Specification see: