gem_hadar 2.0.3 → 2.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca4918a475147350c004d6952b906489dd4f0ecaa9c95695301638e00a2ef68c
-  data.tar.gz: fd7bec7396866c169b09941646c8ac297a2b976e3a7369e4c78a5d969091c53e
+  metadata.gz: d0045014e1b5d18b80ffad7ec652370c6bdcfafdeb6785b2a66789d80d3a535c
+  data.tar.gz: 7fa364fbad07bfe74a4e87cbf876b4bc580afb96b9aa3e1ea89174f9931d9b6d
 SHA512:
-  metadata.gz: 3dee9e9bfead123d2e51b9aa93d80f6969b043962a2ea0934d3104e4f4be7d3fb653d4a1dce2c26f3eb92d981ea3d5a4f1d32814a7d21f13c1be4378db369923
-  data.tar.gz: ee7934c5eb08fdd895d0656fbf78ac71dbeb4be12147951f6d0ba3518468d03097de05876c0793e70b2679fa8b36dec579a160118e868335a4ac33dda153b95f
+  metadata.gz: 79cc671f95e349c1da97f8c86838a4ac34a92c89798781164ae4ee7bccc677615b0f5c93f403a4e3d31f15b45289a3b7be0f79a970ff5024a1c34a1e554ff20d
+  data.tar.gz: 0413c1b0a77170542c1c9b064d77507702035a79d90f01e2e8ab4fe944a25be8c171b8b9c95fad9ecd54e912e3938a8e87449425a4bf0d3fa75070bf40fc740b

data/VERSION

@@ -1 +1 @@
-2.0.3
+2.0.5

data/gem_hadar.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: gem_hadar 2.0.3 ruby lib
+# stub: gem_hadar 2.0.5 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "gem_hadar".freeze
-  s.version = "2.0.3".freeze
+  s.version = "2.0.5".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/lib/gem_hadar/github.rb

@@ -4,6 +4,26 @@ require 'json'
 module GemHadar::GitHub
 end
 
+# A client for creating GitHub releases via the GitHub API.
+#
+# This class provides functionality to interact with the GitHub Releases API,
+# enabling the creation of new releases for a specified repository. It handles
+# the HTTP request setup, including appropriate headers and authentication,
+# and processes the API response to either return the created release data or
+# raise an error if the creation fails.
+#
+# @example Creating a release
+#   creator = GemHadar::GitHub::ReleaseCreator.new(
+#     owner: 'myorg',
+#     repo: 'myrepo',
+#     token: 'ghp_mytoken'
+#   )
+#   release_data = creator.perform(
+#     tag_name: 'v1.0.0',
+#     target_commitish: 'main',
+#     body: 'Release notes here',
+#     name: 'Version 1.0.0'
+#   )
 class GemHadar::GitHub::ReleaseCreator
   class << self
     attr_accessor :github_api_url

data/lib/gem_hadar/prompt_template.rb

@@ -1,3 +1,11 @@
+# A module that provides default prompt templates for interacting with AI models
+# when generating GitHub release changelogs and semantic version bump suggestions.
+#
+# This module contains methods that return system prompts and template strings
+# used by the GemHadar framework to instruct AI models on how to format
+# responses for release notes and versioning decisions. These prompts are
+# designed to produce structured, relevant output that aligns with
+# development workflow requirements.
 module GemHadar::PromptTemplate
   # The default_git_release_system_prompt method returns the system prompt used
   # for generating GitHub release changelogs.

data/lib/gem_hadar/setup.rb

@@ -1,3 +1,14 @@
+# A class that handles the initialization and setup of a new gem project
+# structure.
+#
+# This class is responsible for creating the basic directory layout and
+# configuration files needed for a Ruby gem project. It ensures that essential
+# components like the lib directory, VERSION file, and Rakefile are in place,
+# providing a solid foundation for gem development.
+#
+# @example Setting up a new gem project
+#   setup = GemHadar::Setup.new
+#   setup.perform
 class GemHadar::Setup
   include FileUtils
 

data/lib/gem_hadar/simplecov.rb

@@ -6,8 +6,34 @@ require 'pathname'
 class GemHadar
 end
 
+# A module that provides SimpleCov-related functionality for code coverage
+# analysis.
+#
+# This module encapsulates the setup and configuration of SimpleCov for Ruby
+# projects, including initialization, formatter selection, and warning message
+# handling. It integrates with the GemHadar framework to provide detailed
+# coverage reporting capabilities while maintaining consistent output
+# formatting and error handling.
+#
+# @example Initializing SimpleCov with GemHadar GemHadar::SimpleCov.start
 module GemHadar::SimpleCov
+  # A module that provides warning functionality with colored output.
+  #
+  # This module enhances the standard warn method to display warning messages
+  # in orange color, making them more visible in terminal outputs. It is
+  # designed to be included in classes that need consistent warning message
+  # formatting throughout the application.
+  #
+  # @example Using the warn method from this module
+  #   class MyClass
+  #     include GemHadar::SimpleCov::WarnModule
+  #
+  #     def my_method
+  #       warn "This is a warning message"
+  #     end
+  #   end
   module WarnModule
+    include Term::ANSIColor
     # The warn method displays warning messages using orange colored output.
     #
     # This method takes an array of message strings, applies orange color
@@ -23,6 +49,19 @@ module GemHadar::SimpleCov
     end
   end
 
+  # A formatter class that generates detailed JSON coverage reports from
+  # SimpleCov results.
+  #
+  # This class is responsible for processing code coverage data produced by
+  # SimpleCov and transforming it into a structured JSON format that includes
+  # both line and branch coverage statistics for individual files, as well as
+  # overall project coverage metrics. It calculates various percentages and
+  # counts, then writes the complete coverage data to a dedicated JSON file in
+  # the coverage directory.
+  #
+  # @example Using the ContextFormatter to generate coverage reports
+  #   formatter = GemHadar::SimpleCov::ContextFormatter.new
+  #   formatter.format(simplecov_result)
   class ContextFormatter
     include FileUtils
 

data/lib/gem_hadar/template_compiler.rb

@@ -1,5 +1,19 @@
 require 'erb'
 
+# A class for compiling ERB template files into their final output
+# representations.
+#
+# The TemplateCompiler class provides functionality to process ERB templates,
+# substituting placeholders with actual values from a configuration block. It
+# handles the reading of template files, rendering them with the provided
+# context, and writing the resulting content to specified destination files.
+#
+# @example Compiling a template file
+#   compiler = GemHadar::TemplateCompiler.new do |t|
+#     t.name = 'my_template'
+#     t.version = '1.0.0'
+#   end
+#   compiler.compile('template.erb', 'output.txt')
 class GemHadar::TemplateCompiler
   include Tins::BlockSelf
   include Tins::MethodMissingDelegator::DelegatorModule

data/lib/gem_hadar/utils.rb

@@ -1,5 +1,19 @@
 require 'pathname'
 
+# A module that provides utility methods for handling XDG Base Directory
+# specification compliance.
+#
+# This module offers functionality to determine the appropriate configuration
+# directory based on the XDG Base Directory specification, construct paths for
+# configuration files, and retrieve configuration data from those files. It
+# helps ensure consistent and standardized handling of user configuration files
+# across different operating systems.
+#
+# @example Determining the XDG configuration directory
+#   config_dir = GemHadar::Utils.xdg_config_home
+#
+# @example Retrieving configuration file contents
+#   config_content = GemHadar::Utils.xdg_config('myapp', 'default_value')
 module GemHadar::Utils
   # The xdg_config_home method determines the path to the XDG configuration
   # directory.

data/lib/gem_hadar/version.rb

@@ -1,6 +1,6 @@
 class GemHadar
   # GemHadar version
-  VERSION         = '2.0.3'
+  VERSION         = '2.0.5'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/gem_hadar.rb

@@ -22,6 +22,40 @@ require_maybe 'simplecov'
 require_maybe 'rubygems/package_task'
 require_maybe 'rcov/rcovtask'
 require_maybe 'rspec/core/rake_task'
+
+# A brief description of the GemHadar class.
+#
+# The GemHadar class serves as the primary configuration and task management
+# framework for Ruby gem projects. It provides a DSL for defining gem metadata,
+# dependencies, and Rake tasks, while also offering integration with various
+# tools such as GitHub, SimpleCov, YARD, and Ollama for automating common
+# development workflows.
+#
+# @example Configuring a gem using the GemHadar DSL
+#   GemHadar do
+#     name        'my_gem'
+#     version     '1.0.0'
+#     author      'John Doe'
+#     email       'john@example.com'
+#     homepage    'https://github.com/example/my_gem'
+#     summary     'A brief description'
+#     description 'A longer description of the gem'
+#     test_dir    'spec'
+#   end
+#
+# @example Creating a Rake task for building and packaging the gem
+#   GemHadar do
+#     name 'my_gem'
+#     # ... other configuration ...
+#     build_task
+#   end
+#
+# @example Setting up version bumping with AI assistance
+#   GemHadar do
+#     name 'my_gem'
+#     # ... other configuration ...
+#     version_bump_task
+#   end
 class GemHadar
 end
 require 'gem_hadar/version'
@@ -45,6 +79,12 @@ class GemHadar
   extend DSLKit::DSLAccessor
   include Tins::SecureWrite
 
+  # The initialize method sets up the GemHadar instance by initializing
+  # dependency arrays and evaluating a configuration block.
+  #
+  # @param block [Proc] optional configuration block to set gem properties and settings
+  #
+  # @return [GemHadar] the initialized GemHadar instance
   def initialize(&block)
     @dependencies = []
     @development_dependencies = []
@@ -61,62 +101,263 @@ class GemHadar
     fail "#{self.class}: #{name} has to be set for gem"
   end
 
+  # The developing attribute accessor for configuring development mode.
+  #
+  # This method sets up a DSL accessor for the developing attribute, which
+  # controls whether the gem is in development mode. When set to true, certain
+  # behaviors such as skipping gem pushes are enabled as well as asserting the
+  # validity of the homepage link.
+  #
+  # @return [ Boolean ] the current value of the developing flag
   dsl_accessor :developing, false
 
+  # The name attribute accessor for configuring the gem's name.
+  #
+  # This method sets up a DSL accessor for the name attribute, which specifies
+  # the identifier for the gem. It includes a validation step that raises an
+  # ArgumentError if the name has not been set, ensuring that the gem
+  # configuration contains a required name value.
+  #
+  # @return [ String ] the name of the gem
+  #
+  # @raise [ ArgumentError ] if the name attribute has not been set
   dsl_accessor :name do
     has_to_be_set :name
   end
 
+  # The name_version method computes and returns the combined gem name and
+  # version string.
+  #
+  # This method constructs a version identifier by joining the gem's name and
+  # current version with a hyphen separator. It is typically used to generate
+  # filenames or identifiers that incorporate both the gem name and its version
+  # number for packaging, tagging, or display purposes.
+  #
+  # @return [ String ] the combined gem name and version in the format "name-version"
   dsl_accessor :name_version do
     [ name, version ] * '-'
   end
 
+  # The module_type attribute accessor for configuring the type of Ruby construct to generate for version code.
+  #
+  # This method sets up a DSL accessor for the module_type attribute, which determines whether the generated code
+  # structure for the version module should be a :module or :class. This controls the type of Ruby construct
+  # created when generating code skeletons and version files. The value can be set to either:
+  #
+  # - :module (default) - Generates module-based structure
+  # - :class - Generates class-based structure
+  #
+  # This is used in the generated version.rb file to create either:
+  #
+  #   module MyGem
+  #     # ... version constants
+  #   end
+  #
+  # or
+  #
+  #   class MyGem
+  #     # ... version constants
+  #   end
+  #
+  # @return [ Symbol ] the type of Ruby construct to generate (:module or :class)
   dsl_accessor :module_type, :module
 
+  # The has_to_be_set method raises an error if a required gem configuration
+  # attribute is not set.
+  #
+  # This method is used to validate that essential gem configuration attributes
+  # have been provided. When called, it will raise an ArgumentError with a
+  # descriptive message indicating which attribute is missing and needs to be
+  # configured.
+  #
+  # @param name [ String ] the name of the required attribute
+  #
+  # @raise [ ArgumentError ] if the specified attribute has not been set
   dsl_accessor :author do
     has_to_be_set :author
   end
 
+  # The email attribute accessor for configuring the gem's author email.
+  #
+  # This method sets up a DSL accessor for the email attribute, which specifies
+  # the contact email address for the gem's author. It includes a
+  # validation step that raises an ArgumentError if the email has not been
+  # set, ensuring that the gem configuration contains this required
+  # information.
+  #
+  # @return [ String ] the author's email address
+  #
+  # @raise [ ArgumentError ] if the email attribute has not been set
   dsl_accessor :email do
     has_to_be_set :email
   end
 
+  # The homepage attribute accessor for configuring the gem's homepage URL.
+  #
+  # This method sets up a DSL accessor for the homepage attribute, which
+  # specifies the URL of the gem's official repository or project page. It
+  # includes a validation step that raises an ArgumentError if the homepage has
+  # not been set, ensuring that the gem configuration contains this required
+  # information. When the developing flag is false, it also validates that the
+  # provided URL returns an HTTP OK status after following redirects.
+  #
+  # @return [ String ] the homepage URL of the gem
+  #
+  # @raise [ ArgumentError ] if the homepage attribute has not been set
+  # @raise [ ArgumentError ] if the homepage URL is invalid and developing mode is disabled
   dsl_accessor :homepage do
     has_to_be_set :homepage
   end
 
+  # The summary attribute accessor for configuring the gem's summary.
+  #
+  # This method sets up a DSL accessor for the summary attribute, which
+  # specifies a brief description of what the gem does. It includes a
+  # validation step that raises an ArgumentError if the summary has not been
+  # set, ensuring that the gem configuration contains this required
+  # information.
+  #
+  # @return [ String ] the summary of the gem
+  #
+  # @raise [ ArgumentError ] if the summary attribute has not been set
   dsl_accessor :summary do
     has_to_be_set :summary
   end
 
-  dsl_accessor :description do
-    has_to_be_set :description
-  end
+  # The description attribute accessor for configuring the gem's description.
+  #
+  # This method sets up a DSL accessor for the description attribute, which
+  # specifies the detailed explanation of what the gem does. It includes a
+  # validation step that raises an ArgumentError if the description has not
+  # been set, ensuring that the gem configuration contains this required
+  # information.
+  #
+  # @return [ String ] the description of the gem
+  #
+  # @raise [ ArgumentError ] if the description attribute has not been set
+  dsl_accessor :description do has_to_be_set :description end
 
+  # The require_paths attribute accessor for configuring the gem's require
+  # paths.
+  #
+  # This method sets up a DSL accessor for the require_paths attribute, which
+  # specifies the directories from which the gem's code can be loaded. It
+  # provides a way to define the locations of the library files that will be
+  # made available to users of the gem when it is required in Ruby programs.
+  #
+  # @return [ Set<String> ] a set of directory paths to be included in the load
+  # path
   dsl_accessor :require_paths do Set['lib'] end
 
+  # The require_path method manages the gem's require path configuration.
+  #
+  # This method provides functionality to set or retrieve the directory paths
+  # from which the gem's code can be loaded. When called with a path argument,
+  # it updates the require_paths attribute with that path and returns it.
+  # When called without arguments, it returns the first path from the current
+  # require_paths set.
+  #
+  # @param path [ String, nil ] the directory path to set as the require path;
+  #                           if nil, returns the current first require path
+  #
+  # @return [ String ] the specified path when setting, or the first require
+  # path when retrieving
   def require_path(path = nil)
     if path
       self.require_paths = Set[path]
+      path
     else
       require_paths.first
     end
   end
 
+  # The readme attribute accessor for configuring the gem's README file.
+  #
+  # This method sets up a DSL accessor for the readme attribute, which specifies
+  # the path to the README file for the gem. It provides a way to define the
+  # location of the README file that will be used in documentation and packaging
+  # processes.
+  #
+  # @return [ String, nil ] the path to the README file or nil if not set
   dsl_accessor :readme
 
+  # The title attribute accessor for configuring the gem's documentation title.
+  #
+  # This method sets up a DSL accessor for the title attribute, which specifies
+  # the title to be used in the generated YARD documentation. It provides a way
+  # to define a custom title that will be included in the documentation output,
+  # making it easier to identify and reference the gem's documentation.
+  #
+  # @return [ String, nil ] the documentation title or nil if not set
   dsl_accessor :title
 
+  # The ignore_files attribute accessor for configuring files to be ignored by
+  # the gem.
+  #
+  # This method sets up a DSL accessor for the ignore_files attribute, which
+  # specifies a set of file patterns that should be excluded from various gem
+  # operations and processing tasks. It provides a way to define ignore rules
+  # that apply broadly across the gem's functionality, including but not
+  # limited to build processes, documentation generation, and version control
+  # integration.
+  #
+  # @return [ Set<String> ] a set of file patterns to be ignored by the gem's operations
   dsl_accessor :ignore_files do Set[] end
 
-  dsl_accessor :test_dir
-
+  # The bindir attribute accessor for configuring the gem's binary directory.
+  #
+  # This method sets up a DSL accessor for the bindir attribute, which specifies
+  # the directory where executable scripts (binaries) are installed when the gem
+  # is packaged and installed. It provides a way to define the location of the
+  # bin directory that will contain the gem's executable files.
+  #
+  # @return [ String, nil ] the path to the binary directory or nil if not set
   dsl_accessor :bindir
 
+  # The executables attribute accessor for configuring the gem's executable
+  # files.
+  #
+  # This method sets up a DSL accessor for the executables attribute, which
+  # specifies the list of executable scripts that should be installed as part
+  # of the gem. It provides a way to define one or more executable file names
+  # that will be made available in the gem's bin directory when the gem is
+  # installed.
+  #
+  # @return [ Set<String> ] a set of executable file names to be included with
+  # the gem
   dsl_accessor :executables do Set[] end
 
+  # The licenses attribute accessor for configuring the gem's license
+  # information.
+  #
+  # This method sets up a DSL accessor for the licenses attribute, which
+  # specifies the license(s) under which the gem is distributed. It provides a
+  # way to define one or more licenses that apply to the gem, defaulting to an
+  # empty Set if none are explicitly configured.
+  #
+  # @return [ Set<String> ] a set of license identifiers applied to the gem
   dsl_accessor :licenses do Set[] end
 
+  # The test_dir attribute accessor for configuring the test directory.
+  #
+  # This method sets up a DSL accessor for the test_dir attribute, which specifies
+  # the directory where test files are located. It provides a way to define the
+  # location of the test directory that will be used by various testing tasks and
+  # configurations within the gem project.
+  #
+  # @return [ String, nil ] the path to the test directory or nil if not set
+  dsl_accessor :test_dir
+
+  # The test_files attribute accessor for configuring the list of test files to
+  # be included in the gem package.
+  #
+  # This method sets up a DSL accessor for the test_files attribute, which
+  # specifies the files that should be included when running tests for the gem.
+  # It provides a way to customize the test file discovery process, defaulting
+  # to finding all Ruby files ending in _spec.rb within the spec directory and
+  # its subdirectories.
+  #
+  # @return [ FileList ] a list of file paths to be included in test execution
   dsl_accessor :test_files do
     if test_dir
       FileList[File.join(test_dir, '**/*.rb')]
@@ -125,8 +366,28 @@ class GemHadar
     end
   end
 
+  # The spec_dir attribute accessor for configuring the RSpec specification
+  # directory.
+  #
+  # This method sets up a DSL accessor for the spec_dir attribute, which
+  # specifies the directory where RSpec test files are located. It provides a
+  # way to customize the location of test specifications separate from the
+  # default 'spec' directory, allowing for more flexible project structures.
+  #
+  # @return [ String, nil ] the path to the RSpec specification directory or
+  # nil if not set
   dsl_accessor :spec_dir
 
+  # The spec_pattern method configures the pattern used to locate RSpec test
+  # files.
+  #
+  # This method sets up a DSL accessor for the spec_pattern attribute, which
+  # defines the file pattern used to discover RSpec test files in the project.
+  # It defaults to a standard pattern that looks for files ending in _spec.rb
+  # within the spec directory and its subdirectories, but can be customized
+  # through the configuration block.
+  #
+  # @return [ String ] the file pattern used to locate RSpec test files
   dsl_accessor :spec_pattern do
     if spec_dir
       "#{spec_dir}{,/*/**}/*_spec.rb"
@@ -135,32 +396,123 @@ class GemHadar
     end
   end
 
+  # The doc_files attribute accessor for configuring additional documentation
+  # files.
+  #
+  # This method sets up a DSL accessor for the doc_files attribute, which
+  # specifies additional files to be included in the YARD documentation
+  # generation process. It defaults to an empty FileList and provides a way to
+  # define extra documentation files that should be processed alongside the
+  # standard library source files.
+  #
+  # @return [ FileList ] a list of file paths to be included in YARD
+  # documentation
   dsl_accessor :doc_files do
     FileList[File.join('lib/**/*.rb')] + FileList[File.join('ext/**/*.c')]
   end
 
+  # The yard_dir attribute accessor for configuring the output directory for
+  # YARD documentation.
+  #
+  # This method sets up a DSL accessor for the yard_dir attribute, which
+  # specifies the directory where YARD documentation will be generated. It
+  # defaults to 'doc' and provides a way to customize the documentation output
+  # location through the configuration block.
+  #
+  # @return [ String ] the path to the directory where YARD documentation will be stored
   dsl_accessor :yard_dir do
     'doc'
   end
 
+  # The extensions attribute accessor for configuring project extensions.
+  #
+  # This method sets up a DSL accessor for the extensions attribute, which
+  # specifies the list of extension configuration files (typically extconf.rb)
+  # that should be compiled when building the gem. It defaults to finding all
+  # extconf.rb files within the ext directory and its subdirectories, making it
+  # easy to include native extensions in the gem package.
+  #
+  # @return [ FileList ] a list of file paths to extension configuration files
+  #                      to be compiled during the build process
   dsl_accessor :extensions do FileList['ext/**/extconf.rb'] end
 
+  # The make method retrieves the make command to be used for building
+  # extensions.
+  #
+  # This method determines the appropriate make command to use when compiling
+  # project extensions. It first checks for the MAKE environment variable and
+  # returns its value if set. If the environment variable is not set, it
+  # attempts to detect a suitable make command by testing for the existence of
+  # 'gmake' and 'make' in the system PATH.
+  #
+  # @return [ String, nil ] the make command name or nil if none found
   dsl_accessor :make do
     ENV['MAKE'] || %w[gmake make].find { |c| system(c, '-v') }
   end
 
+  # The files attribute accessor for configuring the list of files included in
+  # the gem package.
+  #
+  # This method sets up a DSL accessor for the files attribute, which specifies
+  # the complete set of files that should be included when building the gem
+  # package. It defaults to retrieving the file list from Git using `git
+  # ls-files` and provides a way to override this behavior through the
+  # configuration block.
+  #
+  # @return [ Array<String> ] an array of file paths to be included in the gem package
   dsl_accessor :files do
     `git ls-files`.split("\n")
   end
 
+  # The package_ignore_files attribute accessor for configuring files to be
+  # ignored during gem packaging.
+  #
+  # This method sets up a DSL accessor for the package_ignore_files attribute,
+  # which specifies file patterns that should be excluded from the gem package
+  # when it is built. It defaults to an empty set and provides a way to define
+  # ignore rules specific to the packaging process, separate from general
+  # project ignore rules.
+  #
+  # @return [ Set<String> ] a set of file patterns to be ignored during gem packaging
   dsl_accessor :package_ignore_files do
     Set[]
   end
 
+  # The path_name attribute accessor for configuring the gem's path name.
+  #
+  # This method sets up a DSL accessor for the path_name attribute, which
+  # determines the raw gem name value used for generating file paths and module
+  # names. It defaults to the value of the name attribute and is particularly
+  # useful for creating consistent directory structures and file naming
+  # conventions. This value is used internally by GemHadar to create the root
+  # directory for the gem and generate a version.rb file in that location.
+  #
+  # @return [ String ] the path name derived from the gem's name
   dsl_accessor :path_name do name end
 
+  # The path_module attribute accessor for configuring the Ruby module name.
+  #
+  # This method sets up a DSL accessor for the path_module attribute, which
+  # determines the camelized version of the gem's name to be used as the Ruby
+  # module or class name. It automatically converts the value of path_name
+  # into CamelCase format, ensuring consistency with Ruby naming conventions
+  # for module and class declarations.
+  #
+  # @return [ String ] the camelized module name derived from path_name
   dsl_accessor :path_module do path_name.camelize end
 
+  # The version attribute accessor for configuring the gem's version.
+  #
+  # This method sets up a DSL accessor for the version attribute, which
+  # specifies the version number of the gem. It includes logic to determine the
+  # version from the VERSION file or an environment variable override, and will
+  # raise an ArgumentError if the version has not been set and cannot be
+  # determined.
+  #
+  # @return [ String ] the version of the gem
+  #
+  # @raise [ ArgumentError ] if the version attribute has not been set and
+  #                           cannot be read from the VERSION file or ENV override
   dsl_accessor :version do
     v = ENV['VERSION'].full? and next v
     File.read('VERSION').chomp
@@ -168,23 +520,91 @@ class GemHadar
     has_to_be_set :version
   end
 
+  # The version_epilogue attribute accessor for configuring additional content
+  # to be appended to the version file.
+  #
+  # This method sets up a DSL accessor for the version_epilogue attribute,
+  # which specifies extra content to be included at the end of the generated
+  # version file. This can be useful for adding custom comments, license
+  # information, or other supplementary data to the version module or class.
+  #
+  # @return [ String, nil ] the epilogue content or nil if not set
   dsl_accessor :version_epilogue
 
+  # The post_install_message attribute accessor for configuring a message to
+  # display after gem installation.
+  #
+  # This method sets up a DSL accessor for the post_install_message attribute,
+  # which specifies a message to be displayed to users after the gem is installed.
+  # This can be useful for providing additional information, usage instructions,
+  # or important warnings to users of the gem.
+  #
+  # @return [ String, nil ] the post-installation message or nil if not set
   dsl_accessor :post_install_message
 
+  # The required_ruby_version attribute accessor for configuring the minimum
+  # Ruby version requirement.
+  #
+  # This method sets up a DSL accessor for the required_ruby_version attribute,
+  # which specifies the minimum version of Ruby that the gem requires to run.
+  # It allows defining the Ruby version constraint that will be included in the
+  # gem specification.
+  #
+  # @return [ String, nil ] the required Ruby version string or nil if not set
   dsl_accessor :required_ruby_version
 
+  # A class that encapsulates Ruby Version Manager (RVM) configuration settings
+  # for a gem project.
+  #
+  # This class is responsible for managing RVM-specific configuration such as
+  # the Ruby version to use and the gemset name. It provides a structured way
+  # to define and access these settings within the context of a GemHadar
+  # configuration.
+  #
+  # @example Configuring RVM settings
+  #   GemHadar do
+  #     rvm do
+  #       use '3.0.0'
+  #       gemset 'my_gem_dev'
+  #     end
+  #   end
   class RvmConfig
     extend DSLKit::DSLAccessor
     include DSLKit::BlockSelf
 
+    # The initialize method sets up the RvmConfig instance by evaluating the
+    # provided block in the context of the object.
+    #
+    # @param block [ Proc ] the block to be evaluated for configuring the RVM settings
+    #
+    # @return [ GemHadar::RvmConfig ] the initialized RvmConfig instance
     def initialize(&block)
       @outer_scope = block_self(&block)
       instance_eval(&block)
     end
 
+    # The use method retrieves or sets the Ruby version to be used with RVM.
+    #
+    # This method serves as an accessor for the Ruby version configuration
+    # within the RVM (Ruby Version Manager) settings. When called without
+    # arguments, it returns the configured Ruby version. When called with
+    # an argument, it sets the Ruby version to be used.
+    #
+    # @return [ String ] the Ruby version string configured for RVM use
+    # @see GemHadar::RvmConfig
     dsl_accessor :use do `rvm tools strings`.split(/\n/).full?(:last) || 'ruby' end
 
+    # The gemset method retrieves or sets the RVM gemset name for the project.
+    #
+    # This method serves as an accessor for the RVM (Ruby Version Manager)
+    # gemset configuration within the nested RvmConfig class. When called
+    # without arguments,
+    # it returns the configured gemset name, which defaults to the gem's name.
+    # When called with an argument, it sets the gemset name to be used with RVM.
+    #
+    # @return [ String ] the RVM gemset name configured for the project
+    # @see GemHadar::RvmConfig#use
+    # @see GemHadar::RvmConfig
     dsl_accessor :gemset do @outer_scope.name end
   end
 
@@ -209,6 +629,17 @@ class GemHadar
     @rvm
   end
 
+  # The default_task_dependencies method manages the list of dependencies for
+  # the default Rake task.
+  #
+  # This method sets up a DSL accessor for the default_task_dependencies
+  # attribute, which specifies the sequence of Rake tasks that must be executed
+  # when running the default task. These dependencies typically include
+  # generating the gem specification and running tests to ensure a consistent
+  # starting point for development workflows.
+  #
+  # @return [ Array<Symbol, String> ] an array of task names that are required
+  #                                   as dependencies for the default task execution
   dsl_accessor :default_task_dependencies, [ :gemspec, :test ]
 
   # The default_task method defines the default Rake task for the gem project.
@@ -222,6 +653,17 @@ class GemHadar
     task :default => default_task_dependencies
   end
 
+  # The build_task_dependencies method manages the list of dependencies for the
+  # build task.
+  #
+  # This method sets up a DSL accessor for the build_task_dependencies
+  # attribute, which specifies the sequence of Rake tasks that must be executed
+  # when running the build task. These dependencies typically include cleaning
+  # previous builds, generating the gem specification, packaging the gem, and
+  # creating a version tag.
+  #
+  # @return [ Array<Symbol, String> ] an array of task names that are required
+  #                                   as dependencies for the build task execution
   dsl_accessor :build_task_dependencies, [ :clobber, :gemspec, :package, :'version:tag' ]
 
   # The build_task method defines a Rake task that orchestrates the complete
@@ -926,6 +1368,16 @@ class GemHadar
     end
   end
 
+  # The push_task_dependencies method manages the list of dependencies for the push task.
+  #
+  # This method sets up a DSL accessor for the push_task_dependencies attribute,
+  # which specifies the sequence of Rake tasks that must be executed when running
+  # the push task. These dependencies typically include checks for modified files,
+  # building the gem, pushing to remote repositories, and publishing to package
+  # managers like RubyGems and GitHub.
+  #
+  # @return [ Array<Symbol, String> ] an array of task names that are required
+  #                                   as dependencies for the push task execution
   dsl_accessor :push_task_dependencies, %i[ modified build master:push version:push gem:push github:release ]
 
   # The push_task method defines a Rake task that orchestrates the complete
@@ -1221,26 +1673,12 @@ class GemHadar
   ensure
     temp_file&.close&.unlink
   end
-  def edit_temp_file(content)
-    editor = ENV.fetch('EDITOR', `which vi`.chomp)
-    unless File.exist?(editor)
-      warn "Can't find EDITOR. => Returning."
-      return
-    end
-    temp_file = Tempfile.new(%w[ changelog .md ])
-    temp_file.write(content)
-    temp_file.close
-
-    unless system("#{editor} #{temp_file.path}")
-      warn "#{editor} returned #{$?.exitstatus} => Returning."
-      return
-    end
-
-    File.read(temp_file.path)
-  ensure
-    temp_file&.close&.unlink
-  end
 
+  # The ollama_model_default method returns the default name of the Ollama AI
+  # model to be used for generating responses when no custom model is
+  # specified.
+  #
+  # @return [ String ] the default Ollama AI model name, which is 'llama3.1'
   dsl_accessor :ollama_model_default, 'llama3.1'.freeze
 
   # The ollama_model method retrieves the name of the Ollama AI model to be
@@ -1557,10 +1995,33 @@ class GemHadar
   end
 end
 
+# The GemHadar method serves as the primary entry point for configuring and
+# initializing a gem project using the GemHadar framework.
+#
+# This method creates a new instance of the GemHadar class, passes the provided
+# block to configure the gem settings, and then invokes the create_all_tasks
+# method to set up all the necessary Rake tasks for the project.
+#
+# @param block [ Proc ] a configuration block used to define gem properties and settings
+#
+# @return [ GemHadar ] the configured GemHadar instance after all tasks have been created
 def GemHadar(&block)
   GemHadar.new(&block).create_all_tasks
 end
 
+# The template method processes an ERB template file and creates a Rake task
+# for its compilation.
+#
+# This method takes a template file path, removes its extension to determine
+# the output file name, and sets up a Rake file task that compiles the template
+# using the provided block configuration. It ensures the source file has an
+# extension and raises an error if not.
+#
+# @param pathname [ String ] the path to the template file to be processed
+#
+# @yield [ block ] the configuration block for the template compiler
+#
+# @return [ Pathname ] the Pathname object representing the destination file path
 def template(pathname, &block)
   template_src = Pathname.new(pathname)
   template_dst = template_src.sub_ext('') # ignore ext, we just support erb anyway

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem_hadar
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.5
 platform: ruby
 authors:
 - Florian Frank