From dd8d3dafc3da6d68fa365d5580e89fc460cf9d94 Mon Sep 17 00:00:00 2001 From: Soumya Ranjan Mahunt Date: Fri, 11 Mar 2022 22:49:12 +0530 Subject: [PATCH] docs: add code documentation --- .github/workflows/main.yml | 13 +++--- Gemfile.lock | 2 +- cocoapods-embed-flutter.gemspec | 12 +++++- example/ios_app/Gemfile.lock | 2 +- lib/cocoapods-embed-flutter.rb | 1 + lib/cocoapods-embed-flutter/flutter.rb | 30 ++++++++++++++ .../flutter/dependency.rb | 4 +- .../flutter/downloader.rb | 7 ++-- .../flutter/external_sources.rb | 40 ++++++++++++++----- .../flutter/pubspec.rb | 13 ++---- lib/cocoapods-embed-flutter/gem_version.rb | 5 +++ lib/cocoapods-embed-flutter/src/pub.rb | 22 +++++++++- 12 files changed, 113 insertions(+), 38 deletions(-) create mode 100644 lib/cocoapods-embed-flutter/flutter.rb diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1e7688f..6b694db 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/Gemfile.lock b/Gemfile.lock index 748e1f6..b4a5dc8 100644 --- a/Gemfile.lock +++ b/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) diff --git a/cocoapods-embed-flutter.gemspec b/cocoapods-embed-flutter.gemspec index 53cb929..d598585 100644 --- a/cocoapods-embed-flutter.gemspec +++ b/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 diff --git a/example/ios_app/Gemfile.lock b/example/ios_app/Gemfile.lock index 78e1600..022ab86 100644 --- a/example/ios_app/Gemfile.lock +++ b/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) diff --git a/lib/cocoapods-embed-flutter.rb b/lib/cocoapods-embed-flutter.rb index ff0584a..4feead1 100644 --- a/lib/cocoapods-embed-flutter.rb +++ b/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' diff --git a/lib/cocoapods-embed-flutter/flutter.rb b/lib/cocoapods-embed-flutter/flutter.rb new file mode 100644 index 0000000..98bae41 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/lib/cocoapods-embed-flutter/flutter/dependency.rb b/lib/cocoapods-embed-flutter/flutter/dependency.rb index 319dddd..97a13f6 100644 --- a/lib/cocoapods-embed-flutter/flutter/dependency.rb +++ b/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? diff --git a/lib/cocoapods-embed-flutter/flutter/downloader.rb b/lib/cocoapods-embed-flutter/flutter/downloader.rb index 4fe6589..c213845 100644 --- a/lib/cocoapods-embed-flutter/flutter/downloader.rb +++ b/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. # diff --git a/lib/cocoapods-embed-flutter/flutter/external_sources.rb b/lib/cocoapods-embed-flutter/flutter/external_sources.rb index ccbac66..ffae435 100644 --- a/lib/cocoapods-embed-flutter/flutter/external_sources.rb +++ b/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,6 +197,9 @@ 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, @@ -192,6 +207,9 @@ def download_request ) 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 diff --git a/lib/cocoapods-embed-flutter/flutter/pubspec.rb b/lib/cocoapods-embed-flutter/flutter/pubspec.rb index 1b6a634..65d648f 100644 --- a/lib/cocoapods-embed-flutter/flutter/pubspec.rb +++ b/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) } diff --git a/lib/cocoapods-embed-flutter/gem_version.rb b/lib/cocoapods-embed-flutter/gem_version.rb index b24ba21..9f327f0 100644 --- a/lib/cocoapods-embed-flutter/gem_version.rb +++ b/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 diff --git a/lib/cocoapods-embed-flutter/src/pub.rb b/lib/cocoapods-embed-flutter/src/pub.rb index 4828710..64218bf 100644 --- a/lib/cocoapods-embed-flutter/src/pub.rb +++ b/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