Merge pull request #5 from devxoul/yard-doc

Add Yard documentation.

.gitignore

@@ -4,6 +4,8 @@
 *.sublime-workspace
 
 .bundle
+.yardoc
+doc
 *.gem
 Gemfile.lock
 test/TestProj

lib/cocoaseeds/core.rb

@@ -1,12 +1,81 @@
 module Seeds
   class Core
+
+    # @return [String] project folder path
+    #
+    attr_reader :root_path
+
+    # @return [Boolean] whether display outputs
+    #
     attr_accessor :mute
 
-    attr_reader :root_path, :seedfile_path, :lockfile_path
-    attr_accessor :project, :seedfile, :lockfile
-    attr_reader :seeds, :locks, :targets
-    attr_reader :source_files, :file_references
+    # @return [String] Seedfile path
+    #
+    # @!visibility private
+    #
+    attr_reader :seedfile_path
+
+    # @return [String] Seedfile.lock path
+    #
+    # @!visibility private
+    #
+    attr_reader :lockfile_path
+
+    # @return [Xcodeproj::Project] Xcode project
+    #
+    # @!visibility private
+    #
+    attr_accessor :project
+
+    # @return [String] content of Seedfile
+    #
+    # @!visibility private
+    #
+    attr_accessor :seedfile
+
+    # @return [String] content of Seedfile.lock
+    #
+    # @!visibility private
+    #
+    attr_accessor :lockfile
+
+    # @return [Hash{Sting => Seeds::Seed}] seeds by seed name
+    #
+    # @!visibility private
+    #
+    attr_reader :seeds
+
+    # @return [Hash{Sting => Seeds::Seed}] locked dependencies by seed name
+    #
+    # @!visibility private
+    #
+    attr_reader :locks
+
+    # @return [Hash{Sting => String}] target name by seed name
+    #
+    # @!visibility private
+    #
+    attr_reader :targets
+
+    # @return [Hash{Sting => Seeds::Seed}] source file paths by seed name
+    #
+    # @!visibility private
+    #
+    attr_reader :source_files
+
+    # @return [Array<Xcodeproj::Project::Object::PBXFileReference>]
+    #         file references that will be added to project
+    #
+    # @!visibility private
+    #
+    attr_reader :file_references
 
+    # @param  [String] root_path
+    #         The path provided will be used for detecting Xcode project and
+    #         Seedfile.
+    #
+    # @see #root_path
+    #
     def initialize(root_path)
       @root_path = root_path
       @seedfile_path = File.join(root_path, "Seedfile")
@@ -18,6 +87,11 @@ def initialize(root_path)
       @file_references = []
     end
 
+    # Read Seedfile and install dependencies. An exception will be raised if
+    # there is no .xcodeproj file or Seedfile in the {#root_path}.
+    #
+    # @see #root_path
+    #
     def install
       self.prepare_requirements
       self.analyze_dependencies
@@ -35,6 +109,13 @@ def install
       @file_references = []
     end
 
+    # Read Xcode project, Seedfile and lockfile. An exception will be raised if
+    # there is no .xcodeproj file or Seedfile in the {#root_path}.
+    #
+    # @see #root_path
+    #
+    # @!visibility private
+    #
     def prepare_requirements
       # .xcodeproj
       project_filename = Dir.glob("#{root_path}/*.xcodeproj")[0]
@@ -57,6 +138,12 @@ def prepare_requirements
       end
     end
 
+    # Parses Seedfile.lockfile into {#lockfile}.
+    #
+    # @see #lockfile
+    #
+    # @!visibility private
+    #
     def analyze_dependencies
       say "Anaylizing dependencies"
 
@@ -72,9 +159,20 @@ def analyze_dependencies
       end
     end
 
+    # Executes {#seedfile} using `eval`
+    #
+    # @!visibility private
+    #
     def execute_seedfile
       @current_target_name = nil
 
+      # Sets `@current_target_name` and executes code block.
+      #
+      # @param [String] names The name of target.
+      #
+      # @!scope method
+      # @!visibility private
+      #
       def target(*names, &code)
         names.each do |name|
           name = name.to_s  # use string instead of symbol
@@ -90,6 +188,13 @@ def target(*names, &code)
         @current_target_name = nil
       end
 
+      # Creates a new instance of {#Seeds::Seed::GitHub} and adds to {#seeds}.
+      #
+      # @see #Seeds::Seed::GitHub
+      #
+      # @!scope method
+      # @!visibility private
+      #
       def github(repo, tag, options={})
         if not @current_target_name  # apply to all targets
           target *self.project.targets.map(&:name) do
@@ -113,6 +218,10 @@ def github(repo, tag, options={})
       eval seedfile
     end
 
+    # Removes disused seeds.
+    #
+    # @!visibility private
+    #
     def remove_seeds
       removings = self.locks.keys - self.seeds.keys
       removings.each do |name|
@@ -122,6 +231,10 @@ def remove_seeds
       end
     end
 
+    # Installs new seeds or updates existing seeds.
+    #
+    # @!visibility private
+    #
     def install_seeds
       self.seeds.sort.each do |name, seed|
         dirname = File.join(self.root_path, "Seeds", name)
@@ -159,6 +272,13 @@ def install_seeds
       end
     end
 
+    # Adds source files to the group 'Seeds' and save its reference to
+    # {#file_references} and removes disused sources files,
+    #
+    # @see #file_references
+    #
+    # @!visibility private
+    #
     def configure_project
       say "Configuring #{self.project.path.basename}"
 
@@ -197,6 +317,10 @@ def configure_project
       end
     end
 
+    # Adds file references to the 'Sources Build Phase'.
+    #
+    # @!visibility private
+    #
     def configure_phase
       self.project.targets.each do |target|
         phase = target.sources_build_phase
@@ -242,6 +366,10 @@ def configure_phase
       end
     end
 
+    # Writes Seedfile.lock file.
+    #
+    # @!visibility private
+    #
     def build_lockfile
       if self.seeds.length > 0
         tree = { "SEEDS" => [] }
@@ -252,6 +380,10 @@ def build_lockfile
       end
     end
 
+    # Prints a message if {#mute} is `false`.
+    #
+    # @see #mute
+    #
     def say(*strings)
       puts strings.join(" ") if not @mute
     end

lib/cocoaseeds/seed.rb

@@ -1,14 +1,33 @@
 module Seeds
   class Seed
-    attr_accessor :name, :version, :url, :files
 
+    # @return [String] the name of the seed
+    #
+    attr_accessor :name
+
+    # @return [String] the version of the seed
+    #
+    attr_accessor :version
+
+    # @return [String] the url of the seed
+    #
+    attr_accessor :url
+
+    # @return [Array<String>] the source file patterns of the seed
+    #
+    attr_accessor :files
+
+    # @return [String] lockfile-formatted string
+    #
+    # @example JLToast (1.2.2)
+    #
     def to_s
       "#{self.name} (#{self.version})"
     end
 
     class GitHub < Seed
       def to_s
-        "#{self.name} (#{self.version}) #{files}"
+        "#{self.name} (#{self.version})"
       end
     end
   end

lib/cocoaseeds/xcodehelper.rb

@@ -2,6 +2,10 @@ module Xcodeproj
 
   class Project
 
+    # Creates a new object with given UUID.
+    #
+    # @param [String] uuid UUID of the object.
+    #
     def new_with_uuid(klass, uuid)
       if klass.is_a?(String)
         klass = Object.const_get(klass)
@@ -11,10 +15,17 @@ def new_with_uuid(klass, uuid)
       object
     end
 
+    # Creates a new group with given UUID.
+    #
+    # @param [String] uuid UUID of the object.
+    #
     def new_group_with_uuid(name, uuid, path = nil, source_tree = :group)
       main_group.new_group_with_uuid(name, uuid, path, source_tree)
     end
 
+    # @param [String] name The name of target.
+    # @return the target with given name
+    #
     def target_named(name)
       self.targets.each do |target|
         if target.name == name.to_s
@@ -31,6 +42,11 @@ def target_named(name)
 module Xcodeproj::Project::Object
 
   class PBXGroup
+
+    # Creates a new group with given UUID.
+    #
+    # @param [String] uuid UUID of the object.
+    #
     def new_group_with_uuid(name, uuid, path = nil, source_tree = :group)
       group = project.new_with_uuid(PBXGroup, uuid)
       children << group
@@ -40,6 +56,11 @@ def new_group_with_uuid(name, uuid, path = nil, source_tree = :group)
       group
     end
 
+
+    # Creates a file reference with given UUID.
+    #
+    # @param [String] uuid UUID of the object.
+    #
     def new_reference_with_uuid(path, uuid, source_tree = :group)
       # customize `FileReferencesFactory.new_file_reference`
       path = Pathname.new(path)
@@ -62,6 +83,9 @@ def new_reference_with_uuid(path, uuid, source_tree = :group)
   end
 
   class PBXNativeTarget
+
+    # @return 'Sources Build Phase' or `nil`
+    #
     def sources_build_phase()
       self.build_phases.each do |phase|
         if phase.kind_of?(Xcodeproj::Project::Object::PBXSourcesBuildPhase)
@@ -73,6 +97,11 @@ def sources_build_phase()
   end
 
   class PBXSourcesBuildPhase
+
+    # Adds the file reference with given UUID.
+    #
+    # @param [String] uuid UUID of the object.
+    #
     def add_file_reference_with_uuid(file_ref, uuid, avoid_duplicates = false)
       if avoid_duplicates && existing = build_file(file_ref)
         existing
@@ -84,6 +113,9 @@ def add_file_reference_with_uuid(file_ref, uuid, avoid_duplicates = false)
       end
     end
 
+    # @return whether the file names match the pattern.
+    # @param [Regexp] pattern The pattern of file name.
+    #
     def include_filename?(pattern)
       self.file_display_names.each do |filename|
         return true if filename.match pattern