cal-invite 0.1.3 → 0.1.4

data/lib/cal_invite/providers/yahoo.rb

@@ -3,9 +3,44 @@
 # lib/cal_invite/providers/yahoo.rb
 module CalInvite
   module Providers
+    # Yahoo Calendar provider for generating calendar event URLs.
+    # This provider generates URLs that open the Yahoo Calendar with a pre-filled
+    # event creation form. Supports all-day events, regular events, and multi-day
+    # sessions with proper timezone handling.
+    #
+    # Note: Yahoo Calendar handles multi-day sessions differently from other providers,
+    # generating separate event URLs for each session.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     description: "Weekly team sync",
+    #     timezone: "America/New_York"
+    #   )
+    #   yahoo = CalInvite::Providers::Yahoo.new(event)
+    #   url = yahoo.generate
+    #
+    # @example Creating a multi-day event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Conference",
+    #     multi_day_sessions: [
+    #       { start_time: Time.parse("2024-04-01 09:00"), end_time: Time.parse("2024-04-01 17:00") },
+    #       { start_time: Time.parse("2024-04-02 09:00"), end_time: Time.parse("2024-04-02 17:00") }
+    #     ]
+    #   )
+    #   urls = CalInvite::Providers::Yahoo.new(event).generate # Returns multiple URLs
     class Yahoo < BaseProvider
+      # Base URL for Yahoo Calendar
       BASE_URL = "https://calendar.yahoo.com"
 
+      # Generates Yahoo Calendar URL(s) for the event.
+      # Handles all event types: all-day, regular, and multi-day sessions.
+      #
+      # @return [String] A single URL for regular or all-day events, or
+      #   multiple URLs (separated by newlines) for multi-day sessions
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate
         if event.all_day
           generate_all_day_event
@@ -18,6 +53,10 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses simplified date format and sets the allday flag.
+      #
+      # @return [String] The Yahoo Calendar URL for an all-day event
       def generate_all_day_event
         start_date = event.start_time || Time.now
         end_date = event.end_time || (start_date + 86400)
@@ -38,6 +77,11 @@ module CalInvite
         "#{BASE_URL}/?#{URI.encode_www_form(params)}"
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      # Includes specific start and end times with timezone information.
+      #
+      # @return [String] The Yahoo Calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
       def generate_single_event
         raise ArgumentError, "Start time is required" unless event.start_time
         raise ArgumentError, "End time is required" unless event.end_time
@@ -61,6 +105,10 @@ module CalInvite
         "#{BASE_URL}/?#{URI.encode_www_form(params)}"
       end
 
+      # Generates multiple URLs for multi-day events, one for each session.
+      # Yahoo Calendar doesn't support multiple sessions in a single URL.
+      #
+      # @return [String] Multiple Yahoo Calendar URLs, one per line
       def generate_multi_day_event
         sessions = event.multi_day_sessions.map do |session|
           params = {
@@ -81,10 +129,19 @@ module CalInvite
         sessions.join("\n")
       end
 
+      # Formats a time object as a date string for Yahoo Calendar.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYYMMDD)
       def format_date(time)
         time.strftime("%Y%m%d")
       end
 
+      # Formats a time object as a UTC timestamp for Yahoo Calendar.
+      # Yahoo Calendar accepts timezone separately in the crnd parameter.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC time (YYYYMMDDTHHmmSSZ)
       def format_time(time)
         # Always use UTC format for the URL, timezone is passed separately
         time.utc.strftime("%Y%m%dT%H%M%SZ")

data/lib/cal_invite/providers.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
-# lib/cal_invite/providers.rb
 require_relative 'providers/base_provider'
 
+# lib/cal_invite/providers.rb
+# Namespace module for all calendar providers supported by CalInvite.
+# Each provider implements the interface defined by BaseProvider.
+#
+# @see CalInvite::Providers::BaseProvider
 module CalInvite
   module Providers
+    # List of supported calendar provider symbols
     SUPPORTED_PROVIDERS = %i[google ical outlook yahoo ics office365].freeze
 
     autoload :Google, 'cal_invite/providers/google'

data/lib/cal_invite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CalInvite
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/lib/cal_invite.rb

@@ -11,17 +11,50 @@ require 'cal_invite/caching'
 require 'cal_invite/event'
 require 'cal_invite/providers'
 
+# The main module for the CalInvite gem. This module provides functionality for generating
+# calendar invites across different calendar providers.
+#
+# @example Configure the gem
+#   CalInvite.configure do |config|
+#     config.timezone = 'America/New_York'
+#     config.cache_store = :memory_store
+#   end
+#
+# @example Create and generate a calendar URL
+#   event = CalInvite::Event.new(
+#     title: "Team Meeting",
+#     start_time: Time.now,
+#     end_time: Time.now + 3600
+#   )
+#   google_url = event.generate_calendar_url(:google)
+#
 module CalInvite
   class Error < StandardError; end
 
   class << self
+    # Returns the current configuration object.
+    # @return [CalInvite::Configuration] The current configuration object
     attr_accessor :configuration
 
+    # Configures the CalInvite gem through a block.
+    #
+    # @yield [config] The configuration object to be modified
+    # @yieldparam config [CalInvite::Configuration] The configuration object
+    # @return [void]
+    #
+    # @example
+    #   CalInvite.configure do |config|
+    #     config.timezone = 'UTC'
+    #     config.cache_store = :memory_store
+    #   end
     def configure
       self.configuration ||= Configuration.new
       yield(configuration)
     end
 
+    # Resets the configuration to default values.
+    #
+    # @return [void]
     def reset_configuration!
       self.configuration = Configuration.new
     end

data/lib/tasks/rdoc.rake

@@ -0,0 +1,13 @@
+# lib/tasks/rdoc.rake
+require 'rdoc/task'
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'CalInvite Documentation'
+  rdoc.main     = 'README.md'
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--charset' << 'UTF-8'
+  rdoc.options << '--markup' << 'markdown'
+  rdoc.rdoc_files.include('README.md', 'LICENSE', 'lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/cal_invite/version.rb')
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cal-invite
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Stephane Paquet
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
 description: CalInvite provides a simple way to generate calendar invite URLs for
   various providers (Google, Outlook, Yahoo) and ICS files
 email:
@@ -32,6 +46,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
+- ".rdoc_options"
 - ".rubocop.yml"
 - CACHING.md
 - CHANGELOG.md
@@ -42,7 +58,9 @@ files:
 - gemfiles/Gemfile.rails6
 - gemfiles/Gemfile.rails7
 - gemfiles/Gemfile.rails8
+- lib/.DS_Store
 - lib/cal_invite.rb
+- lib/cal_invite/.DS_Store
 - lib/cal_invite/caching.rb
 - lib/cal_invite/configuration.rb
 - lib/cal_invite/event.rb
@@ -56,6 +74,7 @@ files:
 - lib/cal_invite/providers/outlook.rb
 - lib/cal_invite/providers/yahoo.rb
 - lib/cal_invite/version.rb
+- lib/tasks/rdoc.rake
 - sig/cal/invite.rbs
 homepage: https://github.com/the-pew-inc/cal-invite
 licenses:
@@ -65,7 +84,21 @@ metadata:
   source_code_uri: https://github.com/the-pew-inc/cal-invite
   changelog_uri: https://github.com/the-pew-inc/cal-invite/blob/master/CHANGELOG.md
 post_install_message:
-rdoc_options: []
+rdoc_options:
+- "--title"
+- CalInvite Documentation
+- "--main"
+- README.md
+- "--line-numbers"
+- "--all"
+- "--charset"
+- UTF-8
+- "--markup"
+- markdown
+- "--exclude"
+- "^(test|spec|features)/"
+- "--exclude"
+- lib/cal_invite/version.rb
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement