timet 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74f9106fb9a60ccd2e2446a58350d3de263459df41ffdf1aa57ca62d267da985
-  data.tar.gz: 77de65d76048301e01e0fb1607862ead7e69ead1647546974ac48b027222b73b
+  metadata.gz: 7b90eeedf6f1653e70f0d90fc2181ebeec88c3788bbc88dbcd072f5a6f2fe821
+  data.tar.gz: c2fbc67fd45bb9d3923a91f737f03fc2a74599193cbe932fbeaadbb44a2d21be
 SHA512:
-  metadata.gz: 409da2fabebd3071832c3c67498015a358cf973e9a41da970969aee97e53e779c8372e9c72c3dad835020644cf163be0138097337ca5589343f3f2364d2d177f
-  data.tar.gz: 537cd9eeba10e3bd43246d3c92f736b91ce171568437e15a22b0a0460171185cc5482f3b45348ef759b4daebb016d59126205f2192a168e618f0445b4384b88b
+  metadata.gz: 475f77e1febf29ccdb1e17bfdd309a829b3d309d4d670afe95ede0926ab897173006ab89d165de4f87c3c3663c5114a08e54ada2f6835453fc4d99fb86134c62
+  data.tar.gz: ca865940ccafb9e60eb682d9085202e3946e1029f5df01b0ece8e998d9dcbe3746f1a196d4638e9a94cb587425198cba4fd93182e2934185d4e849407d34f81c

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.9.1] - 2024-10-04
+
+**Improvements:**
+
+- Added YARD documentation
+- Refactored the `start` method to use `@db.insert_item` directly if the last item status is valid for insertion.
+- Removed the `insert_item_if_valid` private method as it is no longer needed.
+- Updated the README.md to reflect the latest changes and improvements.
+- Added a badge displaying the current gem version in the README.md.
+
 ## [0.9.0] - 2024-10-03
 
 **Improvements:**

data/README.md

@@ -1,10 +1,11 @@
+[![Gem Version](https://badge.fury.io/rb/timet.svg)](https://badge.fury.io/rb/timet)
 ![timet workflow](https://github.com/frankvielma/timet/actions/workflows/ci.yml/badge.svg)
 [![Maintainability](https://api.codeclimate.com/v1/badges/44d57b6c561b9be717f5/maintainability)](https://codeclimate.com/github/frankvielma/timet/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/44d57b6c561b9be717f5/test_coverage)](https://codeclimate.com/github/frankvielma/timet/test_coverage)
 
 # Timet
 
-Timet is a command line time tracking with reports. It's simple to track your hours for work with Timet, whether you're curious about how you allocate your time.
+Timet refers to a command-line tool designed to track your activities by recording the time spent on each task, allowing you to monitor your work hours and productivity directly from your terminal without needing a graphical interface; essentially, it's a way to log your time spent on different projects or tasks using simple text commands
 
 Timet utilizes SQLite to store your time tracking data. This means your data is stored locally and securely, with no need for external databases or cloud storage. This makes Timet lightweight, fast, and perfect for users who value privacy and control over their data.
 
@@ -154,7 +155,6 @@ gem install timet
 | `timet su [start_date]..[end_date]`          | Display a report of tracked time for a date range.                          | `timet su 2024-01-02..2024-01-03`            |
 
 
-
 ### Date Range in Summary
 
 The `timet summary` command now supports specifying a date range for generating reports. This allows users to filter and summarize data within specific date intervals. The date format is in ISO 8601 format (YYYY-MM-DD).

data/lib/timet/application.rb

@@ -19,6 +19,7 @@ module Timet
   class Application < Thor
     include ValidationEditHelper
     include ApplicationHelper
+    include TimeHelper
 
     def initialize(*args)
       super
@@ -36,15 +37,40 @@ module Timet
 
     desc "start [tag] --notes=''", "start time tracking  --notes='my notes...'"
     option :notes, type: :string, desc: 'Add a note'
+    # Starts a new tracking session with the given tag and optional notes.
+    #
+    # @param tag [String] The tag associated with the tracking session. This is a required parameter.
+    # @param notes [String, nil] Optional notes to be associated with the tracking session. If not provided, it defaults to the value in `options[:notes]`.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item and generating a summary.
+    #
+    # @example Start a tracking session with a tag and notes
+    #   start('work', 'Starting work on project X')
+    #
+    # @example Start a tracking session with only a tag
+    #   start('break')
+    #
+    # @note The method uses `TimeHelper.current_timestamp` to get the current timestamp for the start time.
+    # @note The method calls `summary` to generate a summary after inserting the tracking item.
     def start(tag, notes = nil)
       start_time = TimeHelper.current_timestamp
       notes = options[:notes] || notes
 
-      insert_item_if_valid(start_time, tag, notes)
+      @db.insert_item(start_time, tag, notes) if VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
       summary
     end
 
     desc 'stop', 'stop time tracking'
+    # Stops the current tracking session if there is one in progress.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item and generating a summary.
+    #
+    # @example Stop the current tracking session
+    #   stop
+    #
+    # @note The method checks if the last tracking item is in progress by calling `@db.last_item_status`.
+    # @note If the last item is in progress, it fetches the last item's ID using `@db.fetch_last_id` and updates it with the current timestamp.
+    # @note The method then fetches the last item using `@db.last_item` and generates a summary if the result is not nil.
     def stop
       if @db.last_item_status == :in_progress
         last_id = @db.fetch_last_id
@@ -58,6 +84,16 @@ module Timet
     end
 
     desc 'resume (r)', 'resume last task'
+    # Resumes the last tracking session if it was completed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as resuming a tracking session or providing feedback.
+    #
+    # @example Resume the last tracking session
+    #   resume
+    #
+    # @note The method checks the status of the last tracking item using `@db.last_item_status`.
+    # @note If the last item is in progress, it prints a message indicating that a task is currently being tracked.
+    # @note If the last item is complete, it fetches the last item using `@db.last_item`, retrieves the tag and notes, and calls the `start` method to resume the tracking session.
     def resume
       status = @db.last_item_status
 
@@ -77,6 +113,26 @@ module Timet
     desc 'summary (su) [filter] [tag] --csv=csv_filename',
          '  [filter] => [today (t), yesterday (y), week (w), month (m), [start_date]..[end_date]]  [tag]'
     option :csv, type: :string, desc: 'Export to CSV file'
+    # Generates a summary of tracking items based on the provided filter and tag, and optionally exports the summary to a CSV file.
+    #
+    # @param filter [String, nil] The filter to apply when generating the summary. Possible values include 'today', 'yesterday', 'week', 'month', or a date range in the format '[start_date]..[end_date]'.
+    # @param tag [String, nil] The tag to filter the tracking items by.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as displaying the summary and exporting to CSV if specified.
+    #
+    # @example Generate a summary for today
+    #   summary('today')
+    #
+    # @example Generate a summary for a specific tag
+    #   summary(nil, 'work')
+    #
+    # @example Generate a summary for a date range and export to CSV
+    #   summary('2023-01-01..2023-01-31', nil, csv: 'summary.csv')
+    #
+    # @note The method initializes a `TimeReport` object with the database, filter, tag, and optional CSV filename.
+    # @note The method calls `display` on the `TimeReport` object to show the summary.
+    # @note If a CSV filename is provided and there are items to export, the method calls `export_sheet` to export the summary to a CSV file.
+    # @note If no items are found to export, it prints a message indicating that no items were found.
     def summary(filter = nil, tag = nil)
       csv_filename = options[:csv]&.split('.')&.first
       summary = TimeReport.new(@db, filter, tag, csv_filename)
@@ -92,6 +148,25 @@ module Timet
 
     desc 'edit (e) [id] [field] [value]',
          'edit a task, [field] (notes, tag, start or end) and [value] are optional parameters'
+    # Edits a specific tracking item by its ID, allowing the user to modify fields such as notes, tag, start time, or end time.
+    #
+    # @param id [Integer] The ID of the tracking item to be edited.
+    # @param field [String, nil] The field to be edited. Possible values include 'notes', 'tag', 'start', or 'end'. If not provided, the user will be prompted to select a field.
+    # @param new_value [String, nil] The new value to be set for the specified field. If not provided, the user will be prompted to enter a new value.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as updating the tracking item and displaying the updated item.
+    #
+    # @example Edit the notes of a tracking item with ID 1
+    #   edit(1, 'notes', 'Updated notes')
+    #
+    # @example Edit a tracking item with ID 2, prompting for the field and new value
+    #   edit(2)
+    #
+    # @note The method first attempts to find the tracking item by its ID using `@db.find_item(id)`.
+    # @note If the item is found, it displays the current item details using `display_item(item)`.
+    # @note If the field or new value is not provided, the user is prompted to select a field to edit and enter a new value.
+    # @note The method then validates and updates the item using `validate_and_update(item, field, new_value)`.
+    # @note Finally, it displays the updated item details using `display_item(updated_item)`.
     def edit(id, field = nil, new_value = nil)
       item = @db.find_item(id)
       return puts "No tracked time found for id: #{id}" unless item
@@ -107,6 +182,19 @@ module Timet
     end
 
     desc 'delete (d) [id]', 'delete a task'
+    # Deletes a specific tracking item by its ID after confirming with the user.
+    #
+    # @param id [Integer] The ID of the tracking item to be deleted.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item and displaying a confirmation message.
+    #
+    # @example Delete a tracking item with ID 1
+    #   delete(1)
+    #
+    # @note The method first attempts to find the tracking item by its ID using `@db.find_item(id)`.
+    # @note If the item is found, it displays the item details using `TimeReport.new(@db).show_row(item)`.
+    # @note The method then prompts the user for confirmation using `TTY::Prompt.new.yes?('Are you sure you want to delete this entry?')`.
+    # @note If the user confirms, the method deletes the item and prints a confirmation message using `delete_item_and_print_message(id, "Deleted #{id}")`.
     def delete(id)
       item = @db.find_item(id)
       return puts "No tracked time found for id: #{id}" unless item
@@ -118,6 +206,17 @@ module Timet
     end
 
     desc 'cancel (c)', 'cancel active time tracking'
+    # Cancels the active time tracking session by deleting the last tracking item.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as deleting the active tracking item and displaying a confirmation message.
+    #
+    # @example Cancel the active time tracking session
+    #   cancel
+    #
+    # @note The method fetches the ID of the last tracking item using `@db.fetch_last_id`.
+    # @note It checks if the last item is in progress by comparing `@db.last_item_status` with `:complete`.
+    # @note If the last item is in progress, it deletes the item and prints a confirmation message using `delete_item_and_print_message(id, "Canceled active time tracking #{id}")`.
+    # @note If there is no active time tracking, it prints a message indicating that there is no active time tracking.
     def cancel
       id = @db.fetch_last_id
       return puts 'There is no active time tracking' if @db.last_item_status == :complete
@@ -125,18 +224,33 @@ module Timet
       delete_item_and_print_message(id, "Canceled active time tracking #{id}")
     end
 
+    # Determines whether the application should exit when a command fails.
+    #
+    # @return [Boolean] Returns `true`, indicating that the application should exit when a command fails.
+    #
+    # @example Check if the application should exit on failure
+    #   MyClass.exit_on_failure? # => true
+    #
+    # @note This method is typically used in command-line applications to control the behavior when a command fails.
+    # @note Returning `true` means that the application will exit immediately if a command fails, which is useful for ensuring that errors are handled gracefully.
     def self.exit_on_failure?
       true
     end
 
     private
 
-    def insert_item_if_valid(start_time, tag, notes)
-      return unless VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
-
-      @db.insert_item(start_time, tag, notes)
-    end
-
+    # Deletes a tracking item from the database by its ID and prints a confirmation message.
+    #
+    # @param id [Integer] The ID of the tracking item to be deleted.
+    # @param message [String] The message to be printed after the item is deleted.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as deleting the tracking item and printing a message.
+    #
+    # @example Delete a tracking item with ID 1 and print a confirmation message
+    #   delete_item_and_print_message(1, 'Deleted item 1')
+    #
+    # @note The method deletes the tracking item from the database using `@db.delete_item(id)`.
+    # @note After deleting the item, the method prints the provided message using `puts message`.
     def delete_item_and_print_message(id, message)
       @db.delete_item(id)
       puts message

data/lib/timet/application_helper.rb

@@ -3,21 +3,64 @@
 module Timet
   # Provides helper methods for the Timet application.
   module ApplicationHelper
+    # Displays the details of a tracking item.
+    #
+    # @param item [Hash] The tracking item to be displayed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as displaying the item details.
+    #
+    # @example Display the details of a tracking item
+    #   display_item(item)
+    #
+    # @note The method initializes a `TimeReport` object with the database and calls `show_row` to display the item details.
     def display_item(item)
       TimeReport.new(@db).show_row(item)
     end
 
+    # Prompts the user to enter a new value for a specific field of a tracking item.
+    #
+    # @param item [Hash] The tracking item to be edited.
+    # @param field [String] The field to be updated.
+    #
+    # @return [String] The new value entered by the user.
+    #
+    # @example Prompt for a new value for the 'notes' field
+    #   prompt_for_new_value(item, 'notes')
+    #
+    # @note The method retrieves the current value of the field using `field_value`.
+    # @note The method uses `TTY::Prompt.new` to prompt the user for a new value, displaying the current value in the prompt.
     def prompt_for_new_value(item, field)
       current_value = field_value(item, field)
       prompt = TTY::Prompt.new(active_color: :green)
       prompt.ask("Update #{field} (#{current_value}):")
     end
 
+    # Prompts the user to select a field to edit from a list of available fields.
+    #
+    # @return [String] The selected field in lowercase.
+    #
+    # @example Prompt for a field to edit
+    #   select_field_to_edit
+    #
+    # @note The method uses `TTY::Prompt.new` to display a list of available fields for the user to select from.
+    # @note The method returns the selected field in lowercase.
     def select_field_to_edit
       prompt = TTY::Prompt.new(active_color: :green)
       prompt.select('Edit Field?', Timet::Application::FIELD_INDEX.keys.map(&:capitalize), active_color: :cyan).downcase
     end
 
+    # Retrieves the value of a specific field from a tracking item.
+    #
+    # @param item [Hash] The tracking item.
+    # @param field [String] The field to retrieve the value for.
+    #
+    # @return [String, Time] The value of the specified field. If the field is 'start' or 'end', it returns the value as a Time object.
+    #
+    # @example Retrieve the value of the 'notes' field
+    #   field_value(item, 'notes')
+    #
+    # @note The method retrieves the index of the field from `Timet::Application::FIELD_INDEX`.
+    # @note If the field is 'start' or 'end', the method converts the value to a Time object using `TimeHelper.timestamp_to_time`.
     def field_value(item, field)
       index = Timet::Application::FIELD_INDEX[field]
       value = item[index]

data/lib/timet/database.rb

@@ -1,19 +1,42 @@
 # frozen_string_literal: true
 
 require 'sqlite3'
-
+require_relative 'status_helper'
 module Timet
   # Provides database access for managing time tracking data.
   class Database
+    include StatusHelper
+
+    # The default path to the SQLite database file.
     DEFAULT_DATABASE_PATH = File.join(Dir.home, '.timet.db')
 
+    # Initializes a new instance of the Database class.
+    #
+    # @param database_path [String] The path to the SQLite database file. Defaults to DEFAULT_DATABASE_PATH.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as initializing the database connection and creating the necessary tables.
+    #
+    # @example Initialize a new Database instance with the default path
+    #   Database.new
+    #
+    # @example Initialize a new Database instance with a custom path
+    #   Database.new('/path/to/custom.db')
+    #
+    # @note The method creates a new SQLite3 database connection and initializes the necessary tables if they do not already exist.
     def initialize(database_path = DEFAULT_DATABASE_PATH)
       @db = SQLite3::Database.new(database_path)
       create_table
       add_notes
     end
 
-    # Creates the items table if it doesn't already exist
+    # Creates the items table if it doesn't already exist.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to create the table.
+    #
+    # @example Create the items table
+    #   create_table
+    #
+    # @note The method executes SQL to create the 'items' table with columns for id, start, end, and tag.
     def create_table
       execute_sql(<<-SQL)
         CREATE TABLE IF NOT EXISTS items (
@@ -26,6 +49,13 @@ module Timet
     end
 
     # Adds a new column named "notes" to the "items" table if it doesn't exist.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to add the column.
+    #
+    # @example Add the notes column to the items table
+    #   add_notes
+    #
+    # @note The method checks if the 'notes' column already exists and adds it if it does not.
     def add_notes
       table_name = 'items'
       new_column_name = 'notes'
@@ -37,45 +67,129 @@ module Timet
       puts "Column '#{new_column_name}' added to table '#{table_name}'."
     end
 
-    # Inserts a new item into the items table
+    # Inserts a new item into the items table.
+    #
+    # @param start [Integer] The start time of the item.
+    # @param tag [String] The tag associated with the item.
+    # @param notes [String] The notes associated with the item.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to insert the item.
+    #
+    # @example Insert a new item into the items table
+    #   insert_item(1633072800, 'work', 'Completed task X')
+    #
+    # @note The method executes SQL to insert a new row into the 'items' table.
     def insert_item(start, tag, notes)
       execute_sql('INSERT INTO items (start, tag, notes) VALUES (?, ?, ?)', [start, tag, notes])
     end
 
+    # Updates an existing item in the items table.
+    #
+    # @param id [Integer] The ID of the item to be updated.
+    # @param field [String] The field to be updated.
+    # @param value [String, Integer, nil] The new value for the specified field.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to update the item.
+    #
+    # @example Update the tag of an item with ID 1
+    #   update_item(1, 'tag', 'updated_work')
+    #
+    # @note The method executes SQL to update the specified field of the item with the given ID.
     def update_item(id, field, value)
       return if %w[start end].include?(field) && value.nil?
 
       execute_sql("UPDATE items SET #{field}='#{value}' WHERE id = #{id}")
     end
 
+    # Deletes an item from the items table.
+    #
+    # @param id [Integer] The ID of the item to be deleted.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as executing SQL to delete the item.
+    #
+    # @example Delete an item with ID 1
+    #   delete_item(1)
+    #
+    # @note The method executes SQL to delete the item with the given ID from the 'items' table.
     def delete_item(id)
       execute_sql("DELETE FROM items WHERE id = #{id}")
     end
 
-    # Fetches the ID of the last inserted item
+    # Fetches the ID of the last inserted item.
+    #
+    # @return [Integer, nil] The ID of the last inserted item, or nil if no items exist.
+    #
+    # @example Fetch the last inserted item ID
+    #   fetch_last_id
+    #
+    # @note The method executes SQL to fetch the ID of the last inserted item.
     def fetch_last_id
       result = execute_sql('SELECT id FROM items ORDER BY id DESC LIMIT 1').first
       result ? result[0] : nil
     end
 
+    # Fetches the last item from the items table.
+    #
+    # @return [Array, nil] The last item as an array, or nil if no items exist.
+    #
+    # @example Fetch the last item
+    #   last_item
+    #
+    # @note The method executes SQL to fetch the last item from the 'items' table.
     def last_item
       execute_sql('SELECT * FROM items ORDER BY id DESC LIMIT 1').first
     end
 
+    # Determines the status of the last item in the items table.
+    #
+    # @return [Symbol] The status of the last item. Possible values are :no_items, :in_progress, or :complete.
+    #
+    # @example Determine the status of the last item
+    #   last_item_status
+    #
+    # @note The method executes SQL to fetch the last item and determines its status using the `StatusHelper` module.
     def last_item_status
       result = execute_sql('SELECT id, end FROM items ORDER BY id DESC LIMIT 1')
       StatusHelper.determine_status(result)
     end
 
+    # Finds an item in the items table by its ID.
+    #
+    # @param id [Integer] The ID of the item to be found.
+    #
+    # @return [Array, nil] The item as an array, or nil if the item does not exist.
+    #
+    # @example Find an item with ID 1
+    #   find_item(1)
+    #
+    # @note The method executes SQL to find the item with the given ID in the 'items' table.
     def find_item(id)
       execute_sql("select * from items where id=#{id}").first
     end
 
+    # Fetches all items from the items table that have a start time greater than or equal to today.
+    #
+    # @return [Array] An array of items.
+    #
+    # @example Fetch all items from today
+    #   all_items
+    #
+    # @note The method executes SQL to fetch all items from the 'items' table that have a start time greater than or equal to today.
     def all_items
       execute_sql("SELECT * FROM items where start >= '#{Date.today.to_time.to_i}' ORDER BY id DESC")
     end
 
-    # Executes a SQL query and returns the result
+    # Executes a SQL query and returns the result.
+    #
+    # @param sql [String] The SQL query to execute.
+    # @param params [Array] The parameters to bind to the SQL query.
+    #
+    # @return [Array] The result of the SQL query.
+    #
+    # @example Execute a SQL query
+    #   execute_sql('SELECT * FROM items WHERE id = ?', [1])
+    #
+    # @note The method executes the given SQL query with the provided parameters and returns the result.
     def execute_sql(sql, params = [])
       @db.execute(sql, params)
     rescue SQLite3::SQLException => e
@@ -83,12 +197,28 @@ module Timet
       []
     end
 
-    # Closes the database connection
+    # Closes the database connection.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as closing the database connection.
+    #
+    # @example Close the database connection
+    #   close
+    #
+    # @note The method closes the SQLite3 database connection.
     def close
       @db&.close
     end
 
     # Converts a given number of seconds into a human-readable HH:MM:SS format.
+    #
+    # @param seconds [Integer] The number of seconds to convert.
+    #
+    # @return [String] The formatted time in HH:MM:SS format.
+    #
+    # @example Convert 3661 seconds to HH:MM:SS format
+    #   seconds_to_hms(3661) # => '01:01:01'
+    #
+    # @note The method converts the given number of seconds into hours, minutes, and seconds, and formats them as HH:MM:SS.
     def seconds_to_hms(seconds)
       hours, remainder = seconds.divmod(3600)
       minutes, seconds = remainder.divmod(60)

data/lib/timet/formatter.rb

@@ -4,6 +4,14 @@ module Timet
   # This module is responsible for formatting the output of the `timet` application.
   # It provides methods for formatting the table header, separators, and rows.
   module Formatter
+    # Formats the header of the time tracking report table.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the formatted header.
+    #
+    # @example Format and print the table header
+    #   format_table_header
+    #
+    # @note The method constructs a string representing the table header and prints it.
     def format_table_header
       header = <<~TABLE
         Tracked time report \u001b[31m[#{@filter}]\033[0m:
@@ -14,16 +22,42 @@ module Timet
       puts header
     end
 
+    # Formats the separator line for the time tracking report table.
+    #
+    # @return [String] The formatted separator line.
+    #
+    # @example Get the formatted table separator
+    #   format_table_separator # => '+-------+------------+--------+----------+----------+----------+--------------------------+'
+    #
+    # @note The method returns a string representing the separator line for the table.
     def format_table_separator
       '+-------+------------+--------+----------+----------+----------+--------------------------+'
     end
 
+    # Formats a row of the time tracking report table.
+    #
+    # @param row [Array] The row data to be formatted.
+    # @return [String] The formatted row.
+    #
+    # @example Format a table row
+    #   format_table_row(1, 'work', '2023-10-01', '12:00:00', '14:00:00', 7200, 'Completed task X')
+    #
+    # @note The method formats each element of the row and constructs a string representing the formatted row.
     def format_table_row(*row)
       id, tag, start_date, start_time, end_time, duration, notes = row
       "| #{id.to_s.rjust(5)} | #{start_date} | #{tag.ljust(6)} | #{start_time.split[1]} | " \
         "#{end_time.split[1].rjust(8)} | #{@db.seconds_to_hms(duration).rjust(8)} | #{format_notes(notes)}  |"
     end
 
+    # Formats the notes column of the time tracking report table.
+    #
+    # @param notes [String, nil] The notes to be formatted.
+    # @return [String] The formatted notes.
+    #
+    # @example Format notes
+    #   format_notes('This is a long note that needs to be truncated')
+    #
+    # @note The method truncates the notes to a maximum of 20 characters and pads them to a fixed width.
     def format_notes(notes)
       return ' ' * 23 if notes.nil?
 

data/lib/timet/status_helper.rb

@@ -1,8 +1,26 @@
 # frozen_string_literal: true
 
 module Timet
-  # Determines the status of a time tracking result based on the presence and end time of items.
+  # Provides helper methods to determine the status of time tracking results.
   module StatusHelper
+    # Determines the status of a time tracking result based on the presence and end time of items.
+    #
+    # @param result [Array] The result set containing time tracking items.
+    #
+    # @return [Symbol] The status of the time tracking result. Possible values are :no_items, :in_progress, or :complete.
+    #
+    # @example Determine the status of an empty result set
+    #   StatusHelper.determine_status([]) # => :no_items
+    #
+    # @example Determine the status of a result set with an in-progress item
+    #   StatusHelper.determine_status([[1, nil]]) # => :in_progress
+    #
+    # @example Determine the status of a result set with a completed item
+    #   StatusHelper.determine_status([[1, 1633072800]]) # => :complete
+    #
+    # @note The method checks if the result set is empty and returns :no_items if true.
+    # @note If the last item in the result set has no end time, it returns :in_progress.
+    # @note If the last item in the result set has an end time, it returns :complete.
     def self.determine_status(result)
       return :no_items if result.empty?
 

data/lib/timet/time_helper.rb

@@ -7,38 +7,91 @@ module Timet
   # - calculating the duration between two timestamps
   # - converting a Date object to a timestamp
   module TimeHelper
+    # Formats a timestamp into a specific format.
+    #
+    # @param timestamp [Integer] The timestamp to format.
+    # @return [String, nil] The formatted time string in 'YYYY-MM-DD HH:MM:SS' format, or nil if the timestamp is nil.
+    #
+    # @example Format a timestamp
+    #   TimeHelper.format_time(1633072800) # => '2021-10-01 12:00:00'
     def self.format_time(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%Y-%m-%d %H:%M:%S')
     end
 
+    # Converts a timestamp to a date string.
+    #
+    # @param timestamp [Integer] The timestamp to convert.
+    # @return [String, nil] The date string in 'YYYY-MM-DD' format, or nil if the timestamp is nil.
+    #
+    # @example Convert a timestamp to a date string
+    #   TimeHelper.timestamp_to_date(1633072800) # => '2021-10-01'
     def self.timestamp_to_date(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%Y-%m-%d')
     end
 
+    # Converts a timestamp to a time string.
+    #
+    # @param timestamp [Integer] The timestamp to convert.
+    # @return [String, nil] The time string in 'HH:MM:SS' format, or nil if the timestamp is nil.
+    #
+    # @example Convert a timestamp to a time string
+    #   TimeHelper.timestamp_to_time(1633072800) # => '12:00:00'
     def self.timestamp_to_time(timestamp)
       return nil if timestamp.nil?
 
       Time.at(timestamp).strftime('%H:%M:%S')
     end
 
+    # Calculates the duration between two timestamps.
+    #
+    # @param start_time [Integer] The start timestamp.
+    # @param end_time [Integer, nil] The end timestamp. If nil, the current timestamp is used.
+    # @return [Integer] The duration in seconds.
+    #
+    # @example Calculate the duration between two timestamps
+    #   TimeHelper.calculate_duration(1633072800, 1633076400) # => 3600
     def self.calculate_duration(start_time, end_time)
       end_time = end_time ? Time.at(end_time) : current_timestamp
       (end_time - start_time).to_i
     end
 
+    # Converts a Date object to a timestamp.
+    #
+    # @param date [Date] The Date object to convert.
+    # @return [Integer] The timestamp.
+    #
+    # @example Convert a Date object to a timestamp
+    #   TimeHelper.date_to_timestamp(Date.new(2021, 10, 1)) # => 1633072800
     def self.date_to_timestamp(date)
       date.to_time.to_i
     end
 
+    # Calculates the end time based on the start date and end date.
+    #
+    # @param start_date [Date] The start date.
+    # @param end_date [Date, nil] The end date. If nil, the start date + 1 day is used.
+    # @return [Integer] The end timestamp.
+    #
+    # @example Calculate the end time
+    #   TimeHelper.calculate_end_time(Date.new(2021, 10, 1), Date.new(2021, 10, 2)) # => 1633159200
     def self.calculate_end_time(start_date, end_date)
       end_date = end_date ? end_date + 1 : start_date + 1
       date_to_timestamp(end_date)
     end
 
+    # Extracts the date from a list of items based on the index.
+    #
+    # @param items [Array] The list of items.
+    # @param idx [Integer] The index of the current item.
+    # @return [String, nil] The date string in 'YYYY-MM-DD' format, or nil if the date is the same as the previous item.
+    #
+    # @example Extract the date from a list of items
+    #   items = [[1, 1633072800], [2, 1633159200]]
+    #   TimeHelper.extract_date(items, 1) # => '2021-10-02'
     def self.extract_date(items, idx)
       current_start_date = items[idx][1]
       date = TimeHelper.timestamp_to_date(current_start_date)
@@ -50,17 +103,17 @@ module Timet
     # Formats a time string into a standard HH:MM:SS format.
     #
     # @param input [String] The input string to format.
-    # @return [String] The formatted time string in HH:MM:SS format, or nil if the input is invalid.
-    #
-    # @example
-    #  TimeHelper.format_time_string('123456') # => "12:34:56"
-    #  TimeHelper.format_time_string('1234567') # => "12:34:56"
-    #  TimeHelper.format_time_string('1234') # => "12:34:00"
-    #  TimeHelper.format_time_string('123') # => "12:30:00"
-    #  TimeHelper.format_time_string('12') # => "12:00:00"
-    #  TimeHelper.format_time_string('1') # => "01:00:00"
-    #  TimeHelper.format_time_string('127122') # => nil
-    #  TimeHelper.format_time_string('abc') # => nil
+    # @return [String, nil] The formatted time string in HH:MM:SS format, or nil if the input is invalid.
+    #
+    # @example Format a time string
+    #   TimeHelper.format_time_string('123456') # => "12:34:56"
+    #   TimeHelper.format_time_string('1234567') # => "12:34:56"
+    #   TimeHelper.format_time_string('1234') # => "12:34:00"
+    #   TimeHelper.format_time_string('123') # => "12:30:00"
+    #   TimeHelper.format_time_string('12') # => "12:00:00"
+    #   TimeHelper.format_time_string('1') # => "01:00:00"
+    #   TimeHelper.format_time_string('127122') # => nil
+    #   TimeHelper.format_time_string('abc') # => nil
     def self.format_time_string(input)
       return nil if input.nil? || input.empty?
 
@@ -73,6 +126,13 @@ module Timet
       format('%<hours>02d:%<minutes>02d:%<seconds>02d', hours: hours, minutes: minutes, seconds: seconds)
     end
 
+    # Parses time components from a string of digits.
+    #
+    # @param digits [String] The string of digits to parse.
+    # @return [Array] An array containing the hours, minutes, and seconds.
+    #
+    # @example Parse time components
+    #   TimeHelper.parse_time_components('123456') # => [12, 34, 56]
     def self.parse_time_components(digits)
       padded_digits = case digits.size
                       when 1 then "0#{digits}0000"
@@ -85,10 +145,26 @@ module Timet
       padded_digits.scan(/.{2}/).map(&:to_i)
     end
 
+    # Validates the time components.
+    #
+    # @param hours [Integer] The hours component.
+    # @param minutes [Integer] The minutes component.
+    # @param seconds [Integer] The seconds component.
+    # @return [Boolean] True if the time components are valid, otherwise false.
+    #
+    # @example Validate time components
+    #   TimeHelper.valid_time?(12, 34, 56) # => true
+    #   TimeHelper.valid_time?(25, 34, 56) # => false
     def self.valid_time?(hours, minutes, seconds)
       hours < 24 && minutes < 60 && seconds < 60
     end
 
+    # Returns the current timestamp.
+    #
+    # @return [Integer] The current timestamp.
+    #
+    # @example Get the current timestamp
+    #   TimeHelper.current_timestamp
     def self.current_timestamp
       Time.now.utc.to_i
     end

data/lib/timet/time_report.rb

@@ -12,8 +12,26 @@ module Timet
   class TimeReport
     include Formatter
 
-    attr_reader :db, :items, :filename
+    # Provides access to the database instance.
+    attr_reader :db
 
+    # Provides access to the filtered items.
+    attr_reader :items
+
+    # Provides access to the CSV filename.
+    attr_reader :filename
+
+    # Initializes a new instance of the TimeReport class.
+    #
+    # @param db [Database] The database instance to use for fetching data.
+    # @param filter [String, nil] The filter to apply when fetching items. Possible values include 'today', 'yesterday', 'week', 'month', or a date range in the format 'YYYY-MM-DD..YYYY-MM-DD'.
+    # @param tag [String, nil] The tag to filter the items by.
+    # @param csv [String, nil] The filename to use when exporting the report to CSV.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as initializing the instance variables.
+    #
+    # @example Initialize a new TimeReport instance with a filter and tag
+    #   TimeReport.new(db, 'today', 'work', 'report.csv')
     def initialize(db, filter = nil, tag = nil, csv = nil)
       @db = db
       @filename = csv
@@ -21,6 +39,14 @@ module Timet
       @items = filter ? filter_items(@filter, tag) : @db.all_items
     end
 
+    # Displays the report of tracked time entries.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the report.
+    #
+    # @example Display the report
+    #   time_report.display
+    #
+    # @note The method formats and prints the table header, rows, and total duration.
     def display
       return puts 'No tracked time found for the specified filter.' if items.empty?
 
@@ -33,6 +59,16 @@ module Timet
       total
     end
 
+    # Displays a single row of the report.
+    #
+    # @param item [Array] The item to display.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the row.
+    #
+    # @example Display a single row
+    #   time_report.show_row(item)
+    #
+    # @note The method formats and prints the table header, row, and total duration.
     def show_row(item)
       format_table_header
       display_time_entry(item)
@@ -40,6 +76,14 @@ module Timet
       total
     end
 
+    # Exports the report to a CSV file.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as writing the CSV file.
+    #
+    # @example Export the report to a CSV file
+    #   time_report.export_sheet
+    #
+    # @note The method writes the items to a CSV file and prints a confirmation message.
     def export_sheet
       file_name = "#{filename}.csv"
       write_csv(file_name)
@@ -49,6 +93,16 @@ module Timet
 
     private
 
+    # Writes the items to a CSV file.
+    #
+    # @param file_name [String] The name of the CSV file to write.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as writing the CSV file.
+    #
+    # @example Write items to a CSV file
+    #   write_csv('report.csv')
+    #
+    # @note The method writes the items to the specified CSV file.
     def write_csv(file_name)
       CSV.open(file_name, 'w') do |csv|
         csv << %w[ID Start End Tag Notes]
@@ -58,6 +112,16 @@ module Timet
       end
     end
 
+    # Formats an item for CSV export.
+    #
+    # @param item [Array] The item to format.
+    #
+    # @return [Array] The formatted item.
+    #
+    # @example Format an item for CSV export
+    #   format_item(item)
+    #
+    # @note The method formats the item's ID, start time, end time, tag, and notes.
     def format_item(item)
       id, start_time, end_time, tags, notes = item
       [
@@ -69,6 +133,17 @@ module Timet
       ]
     end
 
+    # Displays a single time entry in the report.
+    #
+    # @param item [Array] The item to display.
+    # @param date [String, nil] The date to display. If nil, the date is not displayed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the row.
+    #
+    # @example Display a time entry
+    #   display_time_entry(item, '2021-10-01')
+    #
+    # @note The method formats and prints the row for the time entry.
     def display_time_entry(item, date = nil)
       return puts 'Missing time entry data.' unless item
 
@@ -80,6 +155,14 @@ module Timet
       puts format_table_row(id, tag_name[0..5], start_date, start_time, end_time, duration, notes)
     end
 
+    # Displays the total duration of the tracked time entries.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the total duration.
+    #
+    # @example Display the total duration
+    #   total
+    #
+    # @note The method calculates and prints the total duration of the tracked time entries.
     def total
       total = @items.map do |item|
         TimeHelper.calculate_duration(item[1], item[2])
@@ -88,6 +171,17 @@ module Timet
       puts format_table_separator
     end
 
+    # Filters the items based on the specified filter and tag.
+    #
+    # @param filter [String] The filter to apply.
+    # @param tag [String, nil] The tag to filter the items by.
+    #
+    # @return [Array] The filtered items.
+    #
+    # @example Filter items by date range and tag
+    #   filter_items('2021-10-01..2021-10-31', 'work')
+    #
+    # @note The method filters the items based on the specified date range and tag.
     def filter_items(filter, tag)
       if date_ranges.key?(filter)
         start_date, end_date = date_ranges[filter]
@@ -101,6 +195,14 @@ module Timet
       end
     end
 
+    # Provides predefined date ranges for filtering.
+    #
+    # @return [Hash] A hash containing predefined date ranges.
+    #
+    # @example Get the predefined date ranges
+    #   date_ranges
+    #
+    # @note The method returns a hash with predefined date ranges for 'today', 'yesterday', 'week', and 'month'.
     def date_ranges
       today = Date.today
       {
@@ -111,6 +213,18 @@ module Timet
       }
     end
 
+    # Filters the items by date range and tag.
+    #
+    # @param start_date [Date] The start date of the range.
+    # @param end_date [Date, nil] The end date of the range. If nil, the end date is the start date + 1 day.
+    # @param tag [String, nil] The tag to filter the items by.
+    #
+    # @return [Array] The filtered items.
+    #
+    # @example Filter items by date range and tag
+    #   filter_by_date_range(Date.new(2021, 10, 1), Date.new(2021, 10, 31), 'work')
+    #
+    # @note The method filters the items based on the specified date range and tag.
     def filter_by_date_range(start_date, end_date = nil, tag = nil)
       start_time = TimeHelper.date_to_timestamp(start_date)
       end_time = TimeHelper.calculate_end_time(start_date, end_date)
@@ -120,6 +234,16 @@ module Timet
       )
     end
 
+    # Formats the filter string.
+    #
+    # @param filter [String, nil] The filter string to format.
+    #
+    # @return [String] The formatted filter string.
+    #
+    # @example Format the filter string
+    #   formatted_filter('t') # => 'today'
+    #
+    # @note The method maps shorthand filters to their full names and validates date formats.
     def formatted_filter(filter)
       filter_map = {
         'today' => %w[today t],
@@ -137,6 +261,16 @@ module Timet
       'today'
     end
 
+    # Validates the date format.
+    #
+    # @param date_string [String] The date string to validate.
+    #
+    # @return [Boolean] True if the date format is valid, otherwise false.
+    #
+    # @example Validate the date format
+    #   valid_date_format?('2021-10-01') # => true
+    #
+    # @note The method validates the date format for single dates and date ranges.
     def valid_date_format?(date_string)
       date_format_single = /^\d{4}-\d{2}-\d{2}$/
       date_format_range = /^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$/

data/lib/timet/validation_edit_helper.rb

@@ -6,8 +6,23 @@ module Timet
   # If the field is 'start' or 'end', it checks and updates the value accordingly.
   # Otherwise, it directly updates the field with the new value.
   module ValidationEditHelper
+    # Constants for time fields.
     TIME_FIELDS = %w[start end].freeze
 
+    # Validates and updates a tracking item's field with a new value.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The field to be updated.
+    # @param new_value [String, nil] The new value to be set for the specified field.
+    #
+    # @return [Array, nil] The updated tracking item if the update was successful, otherwise nil.
+    #
+    # @example Validate and update the 'notes' field of a tracking item
+    #   validate_and_update(item, 'notes', 'Updated notes')
+    #
+    # @note The method checks if the field is a time field (start or end) and processes it accordingly.
+    # @note If the field is not a time field, it directly updates the field with the new value.
+    # @note The method returns the updated tracking item if the update was successful.
     def validate_and_update(item, field, new_value)
       return if new_value.nil?
 
@@ -24,6 +39,18 @@ module Timet
 
     private
 
+    # Processes and updates a time field (start or end) of a tracking item.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The time field to be updated.
+    # @param date_value [String] The new value for the time field.
+    # @param id [Integer] The ID of the tracking item.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as updating the time field.
+    #
+    # @note The method formats the date value and checks if it is valid.
+    # @note If the date value is valid, it updates the time field with the new value.
+    # @note If the date value is invalid, it prints an error message.
     def process_and_update_time_field(item, field, date_value, id)
       formatted_date = TimeHelper.format_time_string(date_value)
 
@@ -39,10 +66,28 @@ module Timet
       end
     end
 
+    # Prints an error message for an invalid date.
+    #
+    # @param message [String] The error message to be printed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing an error message.
+    #
+    # @example Print an error message for an invalid date
+    #   print_error('Invalid date: 2023-13-32')
     def print_error(message)
       puts "\u001b[31mInvalid date: #{message}\033[0m"
     end
 
+    # Updates a time field (start or end) of a tracking item with a formatted date value.
+    #
+    # @param item [Array] The tracking item to be updated.
+    # @param field [String] The time field to be updated.
+    # @param formatted_value [String] The formatted date value.
+    #
+    # @return [Time] The updated time value.
+    #
+    # @example Update the 'start' field of a tracking item with a formatted date value
+    #   update_time_field(item, 'start', '2023-10-01 12:00:00')
     def update_time_field(item, field, formatted_value)
       field_index = Timet::Application::FIELD_INDEX[field]
       timestamp = item[field_index]
@@ -51,6 +96,17 @@ module Timet
       DateTime.strptime(current_time.join(' '), '%Y-%m-%d %H:%M:%S %z').to_time
     end
 
+    # Validates if a new time value is valid for a specific time field (start or end).
+    #
+    # @param item [Array] The tracking item to be validated.
+    # @param field [String] The time field to be validated.
+    # @param new_value_epoch [Integer] The new time value in epoch format.
+    # @param id [Integer] The ID of the tracking item.
+    #
+    # @return [Boolean] Returns true if the new time value is valid, otherwise false.
+    #
+    # @example Validate a new 'start' time value
+    #   valid_time_value?(item, 'start', 1633072800, 1)
     def valid_time_value?(item, field, new_value_epoch, id)
       item_start = fetch_item_start(item)
       item_end = fetch_item_end(item)
@@ -64,18 +120,51 @@ module Timet
       end
     end
 
+    # Fetches the start time of a tracking item.
+    #
+    # @param item [Array] The tracking item.
+    #
+    # @return [Integer] The start time in epoch format.
+    #
+    # @example Fetch the start time of a tracking item
+    #   fetch_item_start(item)
     def fetch_item_start(item)
       item[Timet::Application::FIELD_INDEX['start']]
     end
 
+    # Fetches the end time of a tracking item.
+    #
+    # @param item [Array] The tracking item.
+    #
+    # @return [Integer] The end time in epoch format.
+    #
+    # @example Fetch the end time of a tracking item
+    #   fetch_item_end(item)
     def fetch_item_end(item)
       item[Timet::Application::FIELD_INDEX['end']] || TimeHelper.current_timestamp
     end
 
+    # Fetches the end time of the tracking item before the current one.
+    #
+    # @param id [Integer] The ID of the current tracking item.
+    # @param item_start [Integer] The start time of the current tracking item.
+    #
+    # @return [Integer] The end time of the previous tracking item in epoch format.
+    #
+    # @example Fetch the end time of the previous tracking item
+    #   fetch_item_before_end(1, 1633072800)
     def fetch_item_before_end(id, item_start)
       @db.find_item(id - 1)&.dig(Timet::Application::FIELD_INDEX['end']) || item_start
     end
 
+    # Fetches the start time of the tracking item after the current one.
+    #
+    # @param id [Integer] The ID of the current tracking item.
+    #
+    # @return [Integer] The start time of the next tracking item in epoch format.
+    #
+    # @example Fetch the start time of the next tracking item
+    #   fetch_item_after_start(1)
     def fetch_item_after_start(id)
       @db.find_item(id + 1)&.dig(Timet::Application::FIELD_INDEX['start']) || TimeHelper.current_timestamp
     end

data/lib/timet/version.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 module Timet
-  VERSION = '0.9.0'
+  # The version of the Timet application.
+  #
+  # @return [String] The version number in the format 'major.minor.patch'.
+  #
+  # @example Get the version of the Timet application
+  #   Timet::VERSION # => '0.9.1'
+  VERSION = '0.9.1'
 end

data/lib/timet.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+# Require the Timet::Application class from the 'timet/application' file.
+#
+# @note This statement loads the Timet::Application class, which is responsible for handling the command-line interface and user commands.
 require_relative 'timet/application'
+
+# Require the Timet::Database class from the 'timet/database' file.
+#
+# @note This statement loads the Timet::Database class, which provides database access for managing time tracking data.
 require_relative 'timet/database'
+
+# Require the Timet::TimeReport class from the 'timet/time_report' file.
+#
+# @note This statement loads the Timet::TimeReport class, which is responsible for displaying a report of tracked time entries.
 require_relative 'timet/time_report'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timet
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Frank Vielma
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2024-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor