docs: add code documentation

Author: Soumya Mahunt

.github/workflows/main.yml

@@ -10,6 +10,11 @@ on:
     paths-ignore:
       - '*.md'
   workflow_dispatch:
+    inputs:
+      release:
+        description: Create release
+        required: false 
+        type: boolean
 
 env:
   RUBY_VER: 2.6
@@ -62,7 +67,7 @@ jobs:
 
   cd:
     name: Build and Publish
-    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && needs.ci.outputs.release
+    if: (github.event_name == 'push' && needs.ci.outputs.release) || (github.event_name == 'workflow_dispatch' && github.event.inputs.release)
     needs: ci
     runs-on: ubuntu-latest
 
@@ -118,7 +123,7 @@ jobs:
         gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
       env:
         GITHUB_TOKEN: ${{ github.token }}
-        OWNER: ${{ github.actor }}
+        OWNER: ${{ github.repository_owner }}
 
     - name: Publish to RubyGems
       if: steps.conventional_changelog.outputs.skipped == 'false'
@@ -139,7 +144,3 @@ jobs:
         tag: ${{ steps.conventional_changelog.outputs.tag }}
         body: ${{ steps.conventional_changelog.outputs.changelog }}
         artifacts: '*.gem'
-
-    - name: Publish to cocoapods plugins
-      if: steps.conventional_changelog.outputs.skipped == 'false'
-      run: bundle exec rake publish

Gemfile.lock

@@ -11,7 +11,7 @@ GEM
   specs:
     CFPropertyList (3.0.5)
       rexml
-    activesupport (6.1.4.7)
+    activesupport (6.1.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)

cocoapods-embed-flutter.gemspec

@@ -4,6 +4,9 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'cocoapods-embed-flutter/gem_version.rb'
 
 Gem::Specification.new do |spec|
+  repo = 'DartBuild/cocoapods-embed-flutter'
+  repo_url = "https://github.com/#{repo}"
+
   spec.name          = 'cocoapods-embed-flutter'
   spec.version       = CocoapodsEmbedFlutter::VERSION
   spec.authors       = ['Soumya Ranjan Mahunt']
@@ -13,7 +16,7 @@ Gem::Specification.new do |spec|
   Straight forward way of declaring flutter modules as dependency for targets,
   just like cocoapods does with pods.
                          DESC
-  spec.homepage      = 'https://github.com/DartBuild/cocoapods-embed-flutter'
+  spec.homepage      = repo_url
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
@@ -27,4 +30,11 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
+
+  spec.metadata = {
+    'bug_tracker_uri'   => "#{repo_url}/issues",
+    'changelog_uri'     => "#{repo_url}/blob/main/CHANGELOG.md",
+    'source_code_uri'   => repo_url,
+    'github_repo'       => "git@github.com:#{repo}.git"
+  }
 end

example/ios_app/Gemfile.lock

@@ -11,7 +11,7 @@ GEM
   specs:
     CFPropertyList (3.0.5)
       rexml
-    activesupport (6.1.4.7)
+    activesupport (6.1.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)

lib/cocoapods-embed-flutter.rb

@@ -1,3 +1,4 @@
 require 'cocoapods-embed-flutter/gem_version'
 require 'cocoapods-embed-flutter/source'
 require 'cocoapods-embed-flutter/hooks'
+require 'cocoapods-embed-flutter/flutter'

lib/cocoapods-embed-flutter/flutter.rb

@@ -0,0 +1,30 @@
+# The Flutter modules name-spaces all the classes for Flutter.
+#
+module Flutter
+  # The flutter command name.
+  #
+  NAME = 'flutter'.freeze
+  # The directory name for flutter specific
+  # files in a flutter project.
+  #
+  DIR_NAME = 'Flutter'.freeze
+  # The Pub modules name-spaces all the classes for Flutter Pub.
+  #
+  module Pub
+    # The file name for flutter specification declaration.
+    #
+    SPEC_FILE = 'pubspec.yaml'.freeze
+    # The folder name containing flutter dependencies cache files.
+    #
+    TOOL_DIR = '.dart_tool'.freeze
+    # The cache file name for flutter projects.
+    #
+    CACHE_FILE = 'package_config.json'.freeze
+
+    require 'cocoapods-embed-flutter/flutter/downloader'
+    require 'cocoapods-embed-flutter/flutter/external_sources'
+
+    autoload :Dependency,  'cocoapods-embed-flutter/flutter/dependency'
+    autoload :Spec,        'cocoapods-embed-flutter/flutter/pubspec'
+  end
+end

lib/cocoapods-embed-flutter/flutter/dependency.rb

@@ -1,4 +1,4 @@
-require 'cocoapods-embed-flutter/flutter/pubspec'
+require 'cocoapods-embed-flutter/flutter'
 
 module Flutter
   module Pub
@@ -76,7 +76,7 @@ def spec
 
       # Install this dependency for the parent project.
       #
-      # @return void
+      # @return [void]
       #
       def install
         spec.setup if local?

lib/cocoapods-embed-flutter/flutter/downloader.rb

@@ -9,17 +9,16 @@ module Downloader
       # @return [Response] The download response for this download.
       #
       # @param  [Request] request
-      #         the request that describes this pod download.
+      #         the request that describes the flutter project download.
       #
       # @param  [Pathname,Nil] target
-      #         the location to which this pod should be downloaded. If `nil`,
-      #         then the pod will only be cached.
+      #         the location to which the flutter project should be downloaded.
       #
       # @param  [Boolean] can_cache
       #         whether caching is allowed.
       #
       # @param  [Pathname,Nil] cache_path
-      #         the path used to cache pod downloads.
+      #         the path used to cache flutter project downloads.
       #
       # @todo   Implement caching for remote sources.
       #

lib/cocoapods-embed-flutter/flutter/external_sources.rb

@@ -1,11 +1,16 @@
 # Similar to:
 # https://github.com/CocoaPods/CocoaPods/blob/master/lib/cocoapods/external_sources/abstract_external_source.rb
-require 'cocoapods-embed-flutter/flutter/downloader'
+require 'cocoapods-embed-flutter/flutter'
 require 'cocoapods'
 
 module Flutter
   module Pub
+    # The ExternalSources modules name-spaces all the classes
+    # for accessing remote Flutter projects.
+    #
     module ExternalSources
+      # The keys accepted by the hash of the source attribute.
+      #
       SOURCE_KEYS = {
         :git  => [:tag, :branch, :commit, :submodules].freeze,
         :svn  => [:folder, :tag, :revision].freeze,
@@ -97,11 +102,9 @@ def ==(other)
 
         public
 
-        # @!group Subclasses hooks
-
         # Fetches the external source from the remote according to the params.
         #
-        # @param  [Sandbox] sandbox
+        # @param  [Pod::Sandbox] sandbox
         #         the sandbox where the specification should be stored.
         #
         # @return [void]
@@ -138,6 +141,12 @@ def normalized_pupspec_path(declared_path)
           Spec.find_file(name, declared_path)
         end
 
+        # Return the normalized path for a pubspec assuming sandbox
+        # pod folder as location.
+        #
+        # @return [String] The uri of the pubspec appending the name of the file
+        #         and expanding it if necessary.
+        #
         def normalized_pupspec_path
           Spec.find_file(name, target)
         end
@@ -146,21 +155,24 @@ def normalized_pupspec_path
 
         # @! Subclasses helpers
 
-        # Pre-downloads a Pod passing the options to the downloader and informing
-        # the sandbox.
+        # Pre-downloads a flutter project passing the options to the downloader
+        # and informing the sandbox.
         #
-        # @param  [Sandbox] sandbox
-        #         The sandbox where the Pod should be downloaded.
+        # @param  [Pod::Sandbox] sandbox
+        #         The sandbox where the flutter project should be downloaded.
         #
-        # @note   To prevent a double download of the repository the pod is
-        #         marked as pre-downloaded indicating to the installer that only
+        # @note   To prevent a double download of the repository the flutter project
+        #         is marked as pre-downloaded indicating to the installer that only
         #         clean operations are needed.
         #
         # @todo  The downloader configuration is the same of the
-        #        #{PodSourceInstaller} and it needs to be kept in sync.
+        #        #{Pod::Installer::PodSourceInstaller}
+        #        and it needs to be kept in sync.
         #
         # @return [void]
         #
+        # @todo   Implement caching for remote sources.
+        #
         def pre_download(sandbox)
           title = "Pre-downloading: `#{name}` #{description}"
           Pod::UI.titled_section(title,  :verbose_prefix => '-> ') do
@@ -185,13 +197,19 @@ def pre_download(sandbox)
           end
         end
 
+        # @return [Pod::Downloader::Request] the request to remote
+        #         flutter project source.
+        #
         def download_request
           Pod::Downloader::Request.new(
             :name => name,
             :params => params,
           )
         end
 
+        # @return [String] the path where this flutter project
+        #         will be downloaded relative paths.
+        #
         def target
           return Pod::Config.instance.sandbox.pod_dir(name)
         end

lib/cocoapods-embed-flutter/flutter/pubspec.rb

@@ -1,15 +1,8 @@
-require 'cocoapods-embed-flutter/flutter/dependency'
+require 'cocoapods-embed-flutter/flutter'
 require 'yaml'
 
 module Flutter
-  NAME = 'flutter'.freeze
-  DIR_NAME = 'Flutter'.freeze
-
   module Pub
-    SPEC_FILE = 'pubspec.yaml'.freeze
-    TOOL_DIR = '.dart_tool'.freeze
-    CACHE_FILE = 'package_config.json'.freeze
-
     # The Specification provides a DSL to describe a flutter project.
     # A project is defined as a library originating from a source.
     # A specification can support detailed attributes for modules of code
@@ -139,7 +132,7 @@ def setup?
 
       # Sets up the project installing all specified dependencies.
       #
-      # @return void
+      # @return [void]
       #
       def setup
         return if setup?
@@ -149,7 +142,7 @@ def setup
 
       # Runs `flutter pub get` on project directory.
       #
-      # @return void
+      # @return [void]
       #
       def pup_get
         Dir.chdir(project_path) { |path| system('flutter pub get', exception: true) }

lib/cocoapods-embed-flutter/gem_version.rb

@@ -1,3 +1,8 @@
+# The CocoapodsEmbedFlutter modules name-spaces
+# all the plugin specific classes.
+#
 module CocoapodsEmbedFlutter
+  # The version of the cocoapods-embed-flutter.
+  #
   VERSION = '0.5.0'.freeze
 end

lib/cocoapods-embed-flutter/src/pub.rb

@@ -1,8 +1,18 @@
 require 'cocoapods-embed-flutter/gem_version'
-require 'cocoapods-embed-flutter/flutter/pubspec'
-require 'cocoapods-embed-flutter/flutter/external_sources'
+require 'cocoapods-embed-flutter/flutter'
 
+# The Pod modules name-spaces all the classes and methods
+# providing flutter specific functionality to podfile.
+#
 module Pod
+  # The Podfile is a specification that describes the dependencies of the
+  # targets of an Xcode project.
+  #
+  # It supports its own DSL and is stored in a file named `Podfile`.
+  #
+  # The Podfile creates a hierarchy of target definitions that store the
+  # information necessary to generate the CocoaPods libraries.
+  #
   class Podfile
     # The Podfile is a specification that describes the dependencies of the
     # targets of one or more Xcode projects. With Embed Flutter
@@ -104,6 +114,14 @@ def pub(name = nil, *requirements)
         install_flutter_pods_for_pubspec(pubspec)
       end
 
+      # Integrates flutter module provided in `pubspec`
+      # to an Xcode project target.
+      #
+      # @param  [Flutter::Pub::Spec] pubspec
+      #         the flutter module project specification.
+      #
+      # @return [void]
+      #
       def install_flutter_pods_for_pubspec(pubspec)
         raise ArgumentError, "Invalid `pubspec` argument." unless pubspec.is_a?(Flutter::Pub::Spec)
         load pubspec.pod_helper_path