gem_hadar 1.25.0 → 1.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5277b0542113dc8de861927c702b9a17c0dc30fc000b0aad88f77559177bd562
-  data.tar.gz: 32cfd43ba8dd14a74fd0db9cfba009851866f22bb78decd0dd6cbdd0f3cb9b62
+  metadata.gz: f3fefed7b5fd9123e2944de9cf2defcd9f1794aaa7d0058621539b22a2e076d3
+  data.tar.gz: 8734f8f3cf30c0a0b501e5484a58bc5b4bbc4190258133f6de7b1105f17c7383
 SHA512:
-  metadata.gz: a77a1a309790aac939d7aff2f3973c495baa92a3d36e3443747e7243aa0a6e09781a7162ddde5e36868316b85db3ab58c20bcb3f137b818dc5f458ed3b741fd1
-  data.tar.gz: 8754d4b122caf5a5df4af137097440e84a4841f8c0b83fec7e635716997c59cbba36671e6b6b03230dbe1bceb319e131fbfb9c2734a155c8d5771692bfe31289
+  metadata.gz: 867a63019ba90544ba9b0c91478482128d3527221d9c11473929d9f18b5c74673d2fc3ab5844bc26779680b724965a9a7a455518286c5ca9a496342371c31c1a
+  data.tar.gz: a6fa278536336a668d025947b3d9f274d4cc02ae9e2a3d50bb2a2a87b42ee2d351bfb191d9eb472bd215b521c34b561c4ee5d9f15cfcec93576f98871df23c10

data/README.md

@@ -2,7 +2,76 @@
 
 ## Description
 
-Ruby library that provides support for building gems.
+The `gem_hadar` gem is a Ruby library that provides support for building gems
+using rake tasks. It is a comprehensive Ruby gem automation tool that provides:
+
+- **Automated gem building and packaging** - Complete build workflows with
+  🛠️Rake task orchestration
+- **Git workflow automation** - Version management, tagging, remote operations,
+  and repository setup with 🔄git integration
+- **GitHub release management** - Automated release creation with 🤖AI-powered
+  changelog generation using Ollama
+- **Testing framework integration** - Built-in support for RSpec, Test::Unit,
+  and RCov code coverage testing with 🧪testing tools
+- **Documentation generation** - YARD integration with private/public
+  documentation tasks and coverage reporting with 📚documentation
+- **RVM configuration management** - Automatic .rvmrc file generation for
+  consistent development environments with 🎯RVM setup
+- **CI/CD pipeline capabilities** - Complete workflows from build to publish
+  with dependency management using ⚙️CI/CD automation
+- **Semantic versioning automation** - 👾AI-powered version bump suggestions
+  based on code changes
+- **Extension compilation support** - Automatic compilation of C extensions
+  when needed with 🏗️extension building
+- **DSL-based configuration** - Simple block syntax in Rakefile for easy
+  workflow setup with 📝configuration
+- **Gemfile and .gitignore automation** - Automatic creation and management of
+  essential project files with 📦dependency management
+
+## Workflow Diagrams
+
+### Gem Build Process
+```mermaid
+graph LR
+    A[Source Code] --> B[Gemfile Setup]
+    B --> C[Bundle Install]
+    C --> D[Run Tests]
+    D --> E[Generate Documentation]
+    E --> F[Build Gem]
+    F --> G[Version Bump]
+    G --> H[Push to GitHub]
+    G --> I[Push to Rubygems]
+    I --> J[AI Changelog]
+    H --> J[AI Changelog]
+    J --> K[Create Release]
+```
+
+### AI Versioning Flow
+
+```mermaid
+graph LR
+    A[Code Changes] --> B[Semantic Analysis]
+    B --> C[AI Suggestion]
+    C --> D[Version Decision]
+    D --> E[Changelog Generation]
+    E --> F[Release Creation]
+```
+
+### Testing Suite Overview
+
+```mermaid
+graph TD
+    A[Test Run] --> B[RSpec Tests]
+    A[Test Run] --> C[Test::Unit Tests]
+    B --> D[Code Coverage]
+    C --> D[Code Coverage]
+    D --> E[Failures?]
+    E -->|Yes| F[Fix Code]
+    E -->|No| G[Proceed]
+    F --> H[Re-run Tests]
+    H --> I[Success]
+    I --> J[Build Gem]
+```
 
 ## Download
 
@@ -12,37 +81,183 @@ The source of this library is located at
 
 or can be installed via
 
-```
+```bash
 $ gem install gem_hadar
 ```
 
 ## Usage
 
-Create a new directory and excecute
+### Pre-requisites
 
-```
+Before using `gem_hadar`, ensure you have initialized a Git repository in your
+project directory. Many of the gem's commands assume Git is available and
+properly configured in the current working directory.
+
+### Quick Start with Generator
+
+Create a new directory and execute:
+
+```bash
 $ gem_hadar
 ```
 
-Edit the created Rakefile until
+This generates a basic gem structure with a Rakefile. Edit the generated Rakefile until:
 
-```
+```bash
 $ rake gemspec
 ```
 
 and then
 
+```bash
+$ rake build
+```
+
+are performed as desired.
+
+### YARD Documentation
+
+`gem_hadar` supports generating YARD documentation. To generate documentation, run:
+
+```bash
+$ rake doc
 ```
+
+This will create documentation in the `doc` directory using YARD.
+
+### Rakefile Configuration Example
+
+For more advanced control, here's a complete Rakefile configuration example:
+
+```ruby
+# Rakefile
+require 'gem_hadar'
+
+GemHadar do
+  # Set developing to true if you don't have a homepage set yet
+  #developing true
+
+  name        'mygemname'
+  path_name   'mygem'
+  path_module 'Mygem'
+  author      'My name'
+  email       'my@mail'
+  homepage    "https://github.com/younameit/mygem"
+  summary     'Precious gem'
+  description 'Precious detailed gem'
+  test_dir    'spec'
+  ignore      'pkg', 'Gemfile.lock', '.DS_Store'
+
+  readme      'README.md'
+  title       "#{name.camelize} -- My library"
+  licenses    << 'Apache-2.0'
+
+  dependency             'sinatra', '~> 3.2'
+  development_dependency 'rake'
+  development_dependency 'rspec'
+end
+```
+
+Note that `gem_hadar` is ["self hosted"](Rakefile)
+
+### Available Tasks
+
+You can list all available tasks with:
+
+```bash
+$ rake -T
+```
+
+#### Core Tasks
+
+- `rake build` - Build task (builds all packages for a release)
+- `rake release` - Release the new version 1.2.3 for the gem foo
+
+#### Build Tasks
+
+- `rake gemspec` - Create a gemspec file
+- `rake package` - Build all the packages
+- `rake gem` - Build the gem file foo-1.2.3.gem
+- `rake clobber` - Remove any generated files
+- `rake clobber_package` - Remove package products
+- `rake repackage` - Force a rebuild of the package files
+
+#### Version Management
+
+- `rake version` - Writing version information for foo
+- `rake version:show` - Displaying the current version
+- `rake version:list` - List all versions in order
+- `rake version:diff` - Displaying the diff from env var VERSION to the next version or HEAD
+- `rake version:tag` - Tag this commit as version 1.2.3
+- `rake version:bump` - Bump version with AI suggestion
+- `rake version:bump:major` - Bump major version
+- `rake version:bump:minor` - Bump minor version
+- `rake version:bump:build` - Bump build version
+- `rake version:push` - Push version 1.2.3 to all git remotes: origin
+- `rake version:origin:push` - Push version 1.2.3 to git remote origin
+
+#### Documentation
+
+- `rake doc` - Create yard documentation (including private)
+- `rake yard_doc` - Generate YARD Documentation
+- `rake yard:doc` - Create yard documentation
+- `rake yard:private` - Create yard documentation (including private)
+- `rake yard:public` - Create yard documentation
+- `rake yard:clean` - Clean the yard documentation
+- `rake yard:view` - View the yard documentation
+- `rake yard:list-undoc` - List all undocumented classes/modules/methods
+
+#### Testing & Development
+
+- `rake run_specs` - Run RSpec code examples
+- `rake clean` - Remove any temporary products
+- `rake gems:install` - Install all gems from the Gemfile
+- `rake gem_hadar:update` - Update `gem_hadar` to a different version
+- `rake rvm` - Create .rvmrc file
+- `rake default` - Default task
+- `rake compile` - Compile project extensions (if configured)
+
+#### Publishing Tasks
+- `rake push` - Push all changes for version 1.2.3 into the internets
+- `rake github:release` - Create a new GitHub release for the current version
+  with AI-generated changelog
+
+### Update Version
+
+Use one of the following rake tasks to bump the version:
+
+- `rake version:bump:major` - Bump major version (e.g., 1.2.3 → 2.0.0)
+- `rake version:bump:minor` - Bump minor version (e.g., 1.2.3 → 1.3.0)  
+- `rake version:bump:build` - Bump build version (e.g., 1.2.3 → 1.2.4)
+- `rake version:bump` - Get AI-powered suggestion for appropriate bump level
+
+Or bump your [VERSION](./VERSION) file by hand.
+
+### Release
+
+```bash
 $ rake build
 ```
 
-are perfomed as desired.
+This command will execute a series of dependent tasks in order: cleaning
+previous builds, generating the gem specification, packaging the gem, and
+creating a git tag with the current version in git.
+
+After all the files have been changed correctly and the git tags have been
+moved forward to the appropriate commit you can finally enter:
+
+```bash
+$ rake release
+```
+
+The `rake release` command performs the final publishing steps: pushing the
+master branch and version tag to all git remotes, pushing the gem package to
+RubyGems.org, and creating a GitHub release with AI-generated changelog.
 
 ## Author
 
-Florian Frank \<mailto:flori@ping.de\>
-**GemHadar** was written by [Florian Frank](mailto:flori@ping.de)
+**GemHadar** was written by [Florian Frank](mailto:flori@ping.de).
 
 ## License
 
-This software is licensed under the _MIT_ license.
+This software is licensed under the [MIT](./LICENSE) license.

data/VERSION

@@ -1 +1 @@
-1.25.0
+1.26.0

data/gem_hadar.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: gem_hadar 1.25.0 ruby lib
+# stub: gem_hadar 1.26.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "gem_hadar".freeze
-  s.version = "1.25.0".freeze
+  s.version = "1.26.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.24".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.26".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.0".freeze])
   s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.0".freeze])
   s.add_runtime_dependency(%q<ollama-ruby>.freeze, ["~> 1.0".freeze])

data/lib/gem_hadar/prompt_template.rb

@@ -1,4 +1,12 @@
 module GemHadar::PromptTemplate
+  # The default_git_release_system_prompt method returns the system prompt used
+  # for generating GitHub release changelogs.
+  #
+  # This prompt instructs the AI model to act as a Ruby programmer who creates
+  # markdown-formatted changelog entries for new releases. The generated
+  # content helps users understand what has changed in the software.
+  #
+  # @return [ String ] the system prompt for GitHub release changelog generation
   def default_git_release_system_prompt
     <<~EOT
       You are a Ruby programmer generating changelog messages in markdown
@@ -7,6 +15,15 @@ module GemHadar::PromptTemplate
     EOT
   end
 
+  # The default_git_release_prompt method returns the prompt used for
+  # generating GitHub release changelogs.
+  #
+  # This prompt instructs the AI model to create a markdown-formatted changelog
+  # entry for a new release. It specifies guidelines for what constitutes
+  # significant changes, emphasizing the exclusion of trivial updates
+  # and the inclusion of only verified and impactful modifications.
+  #
+  # @return [ String ] the prompt template for GitHub release changelog generation
   def default_git_release_prompt
     <<~EOT
       Output the content of a changelog for the new release of %{name} %{version}
@@ -30,6 +47,16 @@ module GemHadar::PromptTemplate
     EOT
   end
 
+  # The default_version_bump_system_prompt method returns the system prompt
+  # used for generating semantic version bump suggestions.
+  #
+  # This prompt instructs the AI model to act as an expert in semantic versioning,
+  # analyzing provided changes and determining whether a major, minor, or build
+  # version bump is appropriate. It requires the model to provide a brief
+  # explanation of its reasoning followed by a single line containing only one
+  # word: 'major', 'minor', or 'build'.
+  #
+  # @return [ String ] the system prompt for semantic version bump suggestion generation
   def default_version_bump_system_prompt
     <<~EOT
       You are an expert at semantic versioning. Analyze the provided changes
@@ -40,6 +67,16 @@ module GemHadar::PromptTemplate
     EOT
   end
 
+  # The default_version_bump_prompt method returns the prompt template used for
+  # generating semantic version bump suggestions.
+  #
+  # This prompt instructs the AI model to analyze provided changes and
+  # determine whether a major, minor, or build version bump is appropriate
+  # according to Semantic Versioning principles. It requires the model to first
+  # provide a brief explanation of its reasoning, followed by a single line
+  # containing only one word: 'major', 'minor', or 'build'.
+  #
+  # @return [ String ] the prompt template for semantic version bump suggestion generation
   def default_version_bump_prompt
     <<~EOT
       Given the current version %{version} and the following changes:

data/lib/gem_hadar/setup.rb

@@ -1,6 +1,10 @@
 class GemHadar::Setup
   include FileUtils
 
+  # The perform method sets up the basic project structure by creating the lib
+  # directory, initializing a VERSION file with '0.0.0' if it doesn't exist,
+  # and creating a default Rakefile with basic GemHadar configuration if one
+  # doesn't already exist.
   def perform
     mkdir_p 'lib'
     unless File.exist?('VERSION')

data/lib/gem_hadar/template_compiler.rb

@@ -4,12 +4,26 @@ class GemHadar::TemplateCompiler
   include Tins::BlockSelf
   include Tins::MethodMissingDelegator::DelegatorModule
 
+  # The initialize method sets up the template compiler instance by evaluating
+  # the provided block in the context of the object.
+  #
+  # @param block [ Proc ] the block to be evaluated for configuring the template compiler
   def initialize(&block)
     super block_self(&block)
     @values = {}
     instance_eval(&block)
   end
 
+  # The compile method processes an ERB template file and writes the rendered
+  # output to a destination file.
+  #
+  # This method reads the content of a source file, treats it as an ERB
+  # template, and renders it using the provided binding.
+  # The result is then written to a specified destination file, effectively
+  # generating a new file based on the template.
+  #
+  # @param src [ String ] the path to the source ERB template file
+  # @param dst [ String ] the path to the destination file where the rendered content will be written
   def compile(src, dst)
     template = File.read(src)
     File.open(dst, 'w') do |output|
@@ -19,6 +33,21 @@ class GemHadar::TemplateCompiler
     end
   end
 
+  # The method_missing method handles dynamic attribute access and assignment.
+  #
+  # This method intercepts calls to undefined methods on the object, allowing
+  # for dynamic retrieval and setting of values through method calls. If a
+  # method name corresponds to a key in @values and no arguments are provided,
+  # it returns the stored value. If a single argument is provided, it stores
+  # the argument under the method name as a key in @values. For all other
+  # cases, it delegates the call to the superclass implementation.
+  #
+  # @param id [ Symbol ] the name of the method being called
+  # @param a [ Array ] the arguments passed to the method
+  # @param b [ Proc ] the block passed to the method
+  #
+  # @return [ Object ] the value associated with the method name if retrieving,
+  #                    otherwise delegates to super
   def method_missing(id, *a, &b)
     if a.empty? && id && @values.key?(id)
       @values[id]

data/lib/gem_hadar/utils.rb

@@ -1,4 +1,16 @@
 module GemHadar::Utils
+  # The xdg_config_filename method constructs the full path to a configuration
+  # file based on the XDG Base Directory specification.
+  #
+  # It first checks if the XDG_CONFIG_HOME environment variable is set and not
+  # empty. If it is set, the method joins this directory with the provided
+  # filename to form the complete path. If XDG_CONFIG_HOME is not set, it
+  # defaults to using the HOME environment variable to construct the path
+  # within the standard .config directory.
+  #
+  # @param name [ String ] the name of the configuration file
+  #
+  # @return [ String ] the full path to the configuration file
   def xdg_config_filename(name)
     if xdg = ENV['XDG_CONFIG_HOME'].full?
       File.join(xdg, name)
@@ -8,6 +20,17 @@ module GemHadar::Utils
   end
 
   memoize method:
+  # The xdg_config method retrieves configuration data from a file following
+  # the XDG Base Directory specification.
+  #
+  # It checks for the existence of a configuration file using the
+  # xdg_config_filename method and returns its contents if found. If the file
+  # does not exist, it returns the provided default value instead.
+  #
+  # @param name [ String ] the name of the configuration file to retrieve
+  # @param default [ Object ] the default value to return if the configuration file is not found
+  #
+  # @return [ String ] the content of the configuration file or the default value
   def xdg_config(name, default)
     if File.exist?(xdg_config_filename(name))
       File.read(xdg_config_filename(name))

data/lib/gem_hadar/version.rb

@@ -1,6 +1,6 @@
 class GemHadar
   # GemHadar version
-  VERSION         = '1.25.0'
+  VERSION         = '1.26.0'
   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

@@ -51,6 +51,12 @@ class GemHadar
     block and instance_eval(&block)
   end
 
+  # The has_to_be_set method raises an error if a required gem configuration
+  # attribute is not set.
+  #
+  # @param name [ String ] the name of the required attribute
+  #
+  # @raise [ ArgumentError ] if the specified attribute has not been set
   def has_to_be_set(name)
     fail "#{self.class}: #{name} has to be set for gem"
   end
@@ -134,7 +140,7 @@ class GemHadar
   end
 
   dsl_accessor :yard_dir do
-    'yard'
+    'doc'
   end
 
   dsl_accessor :extensions do FileList['ext/**/extconf.rb'] end
@@ -182,6 +188,18 @@ class GemHadar
     dsl_accessor :gemset do @outer_scope.name end
   end
 
+  # The rvm method configures RVM (Ruby Version Manager) settings for the gem
+  # project.
+  #
+  # This method initializes and returns an RvmConfig object that holds RVM-specific
+  # configuration such as the Ruby version to use and the gemset name.
+  # If a block is provided, it configures the RvmConfig object with the given
+  # settings. If no block is provided and no existing RvmConfig object exists,
+  # it creates a new one with default settings.
+  #
+  # @param block [ Proc ] optional block to configure RVM settings
+  #
+  # @return [ GemHadar::RvmConfig ] the RVM configuration object
   def rvm(&block)
     if block
       @rvm = RvmConfig.new(&block)
@@ -193,6 +211,12 @@ class GemHadar
 
   dsl_accessor :default_task_dependencies, [ :gemspec, :test ]
 
+  # The default_task method defines the default Rake task for the gem project.
+  #
+  # This method sets up a Rake task named :default that depends on the tasks
+  # specified in the default_task_dependencies accessor. It provides a convenient
+  # way to run the most common or essential tasks for the project with a single
+  # command.
   def default_task
     desc 'Default task'
     task :default => default_task_dependencies
@@ -200,11 +224,26 @@ class GemHadar
 
   dsl_accessor :build_task_dependencies, [ :clobber, :gemspec, :package, :'version:tag' ]
 
+  # The build_task method defines a Rake task that orchestrates the complete
+  # build process for packaging the gem.
+  #
+  # This method sets up a :build task that depends on the tasks specified in
+  # the build_task_dependencies accessor. It provides a convenient way to
+  # execute all necessary steps for building packages for a release with a
+  # single command.
   def build_task
     desc 'Build task (builds all packages for a release)'
     task :build => build_task_dependencies
   end
 
+  # The install_library method sets up a Rake task for installing the library
+  # or executable into site_ruby directories.
+  #
+  # This method configures an :install task that depends on the
+  # :prepare_install task and executes the provided block. It stores the block
+  # in an instance variable to be called later when the task is executed.
+  #
+  # @param block [ Proc ] the block containing the installation logic
   def install_library(&block)
     @install_library_block = -> do
       desc 'Install executable/library into site_ruby directories'
@@ -212,6 +251,15 @@ class GemHadar
     end
   end
 
+  # The clean method manages the CLEAN file list for Rake tasks.
+  #
+  # When called without arguments, it returns the current CLEAN file list.
+  # When called with arguments, it adds the specified files to the CLEAN list.
+  #
+  # @param args [ Array<String> ] optional list of files to add to the CLEAN list
+  #
+  # @return [ FileList, nil ] the CLEAN file list when no arguments provided,
+  #                           nil otherwise
   def clean(*args)
     if args.empty?
       CLEAN
@@ -220,6 +268,15 @@ class GemHadar
     end
   end
 
+  # The clobber method manages the CLOBBER file list for Rake tasks.
+  #
+  # When called without arguments, it returns the current CLOBBER file list.
+  # When called with arguments, it adds the specified files to the CLOBBER list.
+  #
+  # @param args [ Array<String> ] optional list of files to add to the CLOBBER list
+  #
+  # @return [ FileList, nil ] the CLOBBER file list when no arguments provided,
+  #                           nil otherwise
   def clobber(*args)
     if args.empty?
       CLOBBER
@@ -228,6 +285,15 @@ class GemHadar
     end
   end
 
+  # The ignore method manages the list of files to be ignored by the gem.
+  #
+  # When called without arguments, it returns the current set of ignored files.
+  # When called with arguments, it adds the specified files to the ignore list.
+  #
+  # @param args [ Array<String> ] optional list of file patterns to add to the ignore list
+  #
+  # @return [ Set<String>, nil ] the set of ignored files when no arguments provided,
+  #                           nil otherwise
   def ignore(*args)
     if args.empty?
       ignore_files
@@ -236,6 +302,17 @@ class GemHadar
     end
   end
 
+  # The package_ignore method manages the list of files to be ignored during
+  # gem packaging.
+  #
+  # When called without arguments, it returns the current set of package ignore
+  # files. When called with arguments, it adds the specified file patterns to
+  # the package ignore list.
+  #
+  # @param args [ Array<String> ] optional list of file patterns to add to the package ignore list
+  #
+  # @return [ Set<String>, nil ] the set of package ignore files when no arguments provided,
+  #                           nil otherwise
   def package_ignore(*args)
     if args.empty?
       package_ignore_files
@@ -244,14 +321,28 @@ class GemHadar
     end
   end
 
+  # The dependency method adds a new runtime dependency to the gem.
+  #
+  # @param args [ Array ] the arguments defining the dependency
   def dependency(*args)
     @dependencies << args
   end
 
+  # The development_dependency method adds a new development-time dependency to
+  # the gem.
+  #
+  # @param args [ Array ] the arguments defining the development dependency
   def development_dependency(*args)
     @development_dependencies << args
   end
 
+  # The gems_install_task method defines a Rake task for installing all gem
+  # dependencies specified in the Gemfile.
+  #
+  # This method sets up a :gems:install task that executes a block to install
+  # gems. If no block is provided, it defaults to running 'bundle install'.
+  #
+  # @param block [ Proc ] optional block containing the installation command
   def gems_install_task(&block)
     block ||= proc {  sh 'bundle install' }
     desc 'Install all gems from the Gemfile'
@@ -260,6 +351,14 @@ class GemHadar
     end
   end
 
+  # The version_task method defines a Rake task that generates a version file
+  # for the gem.
+  #
+  # This method creates a task named :version that writes version information
+  # to a Ruby file in the lib directory. The generated file contains constants
+  # for the version and its components, as well as an optional epilogue
+  # section. The task ensures the target directory exists and uses secure file
+  # writing to prevent permission issues.
   def version_task
     desc m = "Writing version information for #{name}-#{version}"
     task :version do
@@ -281,6 +380,13 @@ class GemHadar
     end
   end
 
+  # The version_show_task method defines a Rake task that displays the current
+  # version of the gem.
+  #
+  # This method creates a :version:show task under the Rake namespace that
+  # reads the version from the generated version file in the lib directory and
+  # compares it with the version specified in the GemHadar configuration. It
+  # then outputs a message indicating whether the versions match or not.
   def version_show_task
     namespace :version do
       desc "Displaying the current version"
@@ -299,6 +405,21 @@ class GemHadar
     end
   end
 
+  # The version_log_diff method generates a git log output containing patch
+  # differences between two specified versions.
+  #
+  # This method retrieves the commit history between a starting version and an
+  # ending version, including detailed changes (patch format) for each commit.
+  # It supports comparing against the current HEAD or specific version tags,
+  # and automatically determines the appropriate previous version when only a
+  # target version is provided.
+  #
+  # @param to_version [ String ] the ending version tag or 'HEAD' to compare up to the latest commit
+  # @param from_version [ String, nil ] the starting version tag; if nil, it defaults based on to_version
+  #
+  # @raise [ RuntimeError ] if the specified version tags are not found in the repository
+  #
+  # @return [ String ] the git log output in patch format showing changes between the two versions
   def version_log_diff(to_version: 'HEAD', from_version: nil)
     if to_version == 'HEAD'
       if from_version.blank?
@@ -331,6 +452,15 @@ class GemHadar
     end
   end
 
+  # The version_diff_task method defines Rake tasks for listing and displaying
+  # git version differences.
+  #
+  # This method sets up two subtasks under the :version namespace:
+  #
+  # - A :list task that fetches all git tags, ensures the operation succeeds,
+  # and outputs the sorted list of versions.
+  # - A :diff task that calculates the version range, displays a colored diff
+  # between the versions, and shows the changes.
   def version_diff_task
     namespace :version do
       desc "List all versions in order"
@@ -349,9 +479,18 @@ class GemHadar
     end
   end
 
+  # The gem_hadar_update_task method defines a Rake task that updates the
+  # gem_hadar dependency version in the gemspec file.
+  #
+  # This method creates a :gem_hadar:update task under the Rake namespace that
+  # prompts the user to specify a new gem_hadar version.
+  # It then reads the existing gemspec file, modifies the version constraint
+  # for the gem_hadar dependency, and writes the updated content back to the
+  # file. If the specified version is already present in the gemspec, it skips
+  # the update and notifies the user.
   def gem_hadar_update_task
     namespace :gem_hadar do
-      desc 'Update gem_hadar a different version'
+      desc 'Update gem_hadar to a different version'
       task :update do
         answer = ask?("Which gem_hadar version? ", /^((?:\d+.){2}(?:\d+))$/)
         unless answer
@@ -377,6 +516,14 @@ class GemHadar
     end
   end
 
+  # The gemspec_task method defines a Rake task that generates and writes a
+  # gemspec file for the project.
+  #
+  # This method creates a :gemspec task that depends on the :version task,
+  # ensuring the version is set before generating the gemspec. It constructs
+  # the filename based on the project name, displays a warning message
+  # indicating the file being written, and uses secure_write to create the
+  # gemspec file with content generated by the gemspec method.
   def gemspec_task
     desc 'Create a gemspec file'
     task :gemspec => :version do
@@ -386,6 +533,12 @@ class GemHadar
     end
   end
 
+  # The package_task method sets up a Rake task for packaging the gem.
+  #
+  # This method configures a task that creates a package directory, initializes
+  # a Gem::PackageTask with the current gem specification, and specifies that
+  # tar files should be created. It also includes the files to be packaged by
+  # adding gem_files to the package_files attribute of the Gem::PackageTask.
   def package_task
     clean 'pkg'
     Gem::PackageTask.new(gemspec) do |pkg|
@@ -394,24 +547,20 @@ class GemHadar
     end
   end
 
+  # The install_library_task method executes the installed library task block
+  # if it has been defined.
   def install_library_task
     @install_library_block.full?(:call)
   end
 
-  def doc_task
-    clean 'doc'
-    desc "Creating documentation"
-    task :doc do
-      sh 'yard doc'
-      cmd = 'yardoc'
-      if readme
-        cmd << " --readme '#{readme}'"
-      end
-      cmd << ' - ' << doc_files * ' '
-      sh cmd
-    end
-  end
-
+  # The test_task method sets up a Rake task for executing the project's test
+  # suite.
+  #
+  # This method configures a Rake task named :test that runs the test suite
+  # using Rake::TestTask. It includes the test directory and required paths in
+  # the load path, specifies the test files to run, and enables verbose output.
+  # The task also conditionally depends on the :compile task if project
+  # extensions are present.
   def test_task
     tt =  Rake::TestTask.new(:run_tests) do |t|
       t.libs << test_dir
@@ -423,6 +572,12 @@ class GemHadar
     task :test => [ (:compile if extensions.full?), tt.name ].compact
   end
 
+  # The spec_task method sets up a Rake task for executing RSpec tests.
+  #
+  # This method configures a :spec task that runs the project's RSpec test
+  # suite. It initializes an RSpec::Core::RakeTask with appropriate Ruby
+  # options, test pattern, and verbose output. The task also conditionally
+  # depends on the :compile task if project extensions are present.
   def spec_task
     defined? ::RSpec::Core::RakeTask or return
     st =  RSpec::Core::RakeTask.new(:run_specs) do |t|
@@ -434,6 +589,15 @@ class GemHadar
     task :spec => [ (:compile if extensions.full?), st.name ].compact
   end
 
+  # The rcov_task method sets up a Rake task for executing code coverage tests
+  # using RCov.
+  #
+  # This method configures a :rcov task that runs the project's test suite with
+  # RCov to generate code coverage reports. It includes the test directory and
+  # required paths in the load path, specifies the test files to run, and
+  # enables verbose output. The task also conditionally depends on the :compile
+  # task if project extensions are present. If RCov is not available, it
+  # displays a warning message suggesting to install RCov.
   def rcov_task
     if defined?(::Rcov)
       rt = ::Rcov::RcovTask.new(:run_rcov) do |t|
@@ -455,6 +619,23 @@ class GemHadar
     end
   end
 
+  # The version_bump_task method defines Rake tasks for incrementing the gem's
+  # version number.
+  #
+  # This method sets up a hierarchical task structure under the :version
+  # namespace:
+  #
+  # - It creates subtasks in the :version:bump namespace for explicitly bumping
+  # major, minor, or build versions.
+  # - It also defines a :version:bump task that automatically suggests the
+  # appropriate version bump type by analyzing recent changes using AI. The
+  # suggestion is based on the git log diff between the previous version and
+  # the current HEAD, and it prompts the user for confirmation before applying
+  # the bump.
+  #
+  # The tasks utilize the version_log_diff method to gather change information,
+  # the ollama_generate method to get AI-powered suggestions, and the
+  # version_bump_to method to perform the actual version update.
   def version_bump_task
     namespace :version do
       namespace :bump do
@@ -474,7 +655,7 @@ class GemHadar
         end
       end
 
-      desc 'Bump version with suggestion'
+      desc 'Bump version with AI suggestion'
       task :bump do
         log_diff = version_log_diff(from_version: nil, to_version: 'HEAD')
         system   = xdg_config('version_bump_system_prompt.txt', default_version_bump_system_prompt)
@@ -499,6 +680,15 @@ class GemHadar
     end
   end
 
+  # The version_tag_task method defines a Rake task that creates a Git tag for
+  # the current version.
+  #
+  # This method sets up a :version:tag task under the Rake namespace that
+  # creates an annotated Git tag for the project's current version. It checks
+  # if a tag with the same name already exists and handles the case where the
+  # tag exists but is different from the current commit. If the tag already
+  # exists and is different, it prompts the user to confirm whether to
+  # overwrite it forcefully.
   def version_tag_task
     namespace :version do
       desc "Tag this commit as version #{version}"
@@ -523,10 +713,24 @@ class GemHadar
     end
   end
 
+  # The git_remote method retrieves the primary Git remote name configured for
+  # the project.
+  #
+  # It first checks the GIT_REMOTE environment variable for a custom remote
+  # specification. If not set, it defaults to 'origin'. When multiple remotes
+  # are specified in the environment variable, only the first one is returned.
   def git_remote
     ENV.fetch('GIT_REMOTE', 'origin').split(/\s+/).first
   end
 
+  # The master_prepare_task method defines a Rake task that sets up a remote
+  # Git repository for the project.
+  #
+  # This method creates a :master:prepare task under the Rake namespace that
+  # guides the user through creating a new bare Git repository on a remote
+  # server via SSH. It prompts for the remote name, directory path, and SSH
+  # account details to configure the repository and establish a connection back
+  # to the local project.
   def master_prepare_task
     namespace :master do
       desc "Prepare a remote git repository for this project"
@@ -544,6 +748,20 @@ class GemHadar
     end
   end
 
+  # The version_push_task method defines Rake tasks for pushing version tags to
+  # Git remotes.
+  #
+  # This method sets up a hierarchical task structure under the :version
+  # namespace:
+  #
+  # - It creates subtasks in the :version:push namespace for each configured
+  # Git remote, allowing individual pushes to specific remotes.
+  # - It also defines a top-level :version:push task that depends on all the
+  # individual remote push tasks, enabling a single command to push the version
+  # tag to all remotes.
+  #
+  # The tasks utilize the git_remotes method to determine which remotes are
+  # configured and generate appropriate push commands for each one.
   def version_push_task
     namespace :version do
       git_remotes.each do |gr|
@@ -560,6 +778,19 @@ class GemHadar
     end
   end
 
+  # The master_push_task method defines Rake tasks for pushing the master
+  # branch to configured Git remotes.
+  #
+  # This method sets up a hierarchical task structure under the :master namespace:
+  #
+  # - It creates subtasks in the :master:push namespace for each configured Git
+  #   remote, allowing individual pushes to specific remotes.
+  # - It also defines a top-level :master:push task that depends on all the individual
+  #   remote push tasks, enabling a single command to push the master branch to
+  #   all remotes.
+  #
+  # The tasks utilize the git_remotes method to determine which remotes are
+  # configured and generate appropriate push commands for each one.
   def master_push_task
     namespace :master do
       git_remotes.each do |gr|
@@ -576,6 +807,17 @@ class GemHadar
     end
   end
 
+  # The gem_push_task method defines a Rake task for pushing the generated gem
+  # file to RubyGems.
+  #
+  # This method sets up a :gem:push task under the Rake namespace that handles
+  # the process of uploading the gem package to RubyGems. It checks if the
+  # project is in developing mode and skips the push operation if so.
+  # Otherwise, it verifies the existence of the gem file, prompts the user for
+  # confirmation before pushing, and uses the gem push command with an optional
+  # API key from the environment. If the gem file does not exist or the user
+  # declines to push, appropriate messages are displayed and the task exits
+  # accordingly.
   def gem_push_task
     namespace :gem do
       path = "pkg/#{name_version}.gem"
@@ -604,6 +846,15 @@ class GemHadar
     end
   end
 
+  # The git_remotes_task method defines a Rake task that displays all Git
+  # remote repositories configured for the project.
+  #
+  # This method sets up a :git_remotes task under the Rake namespace that
+  # retrieves and prints the list of Git remotes along with their URLs. It uses
+  # the git_remotes method to obtain the remote names and then fetches each
+  # remote's URL using the `git remote get-url` command. The output is
+  # formatted to show each remote name followed by its corresponding URL on
+  # separate lines.
   def git_remotes_task
     task :git_remotes do
       puts git_remotes.map { |r|
@@ -613,6 +864,14 @@ class GemHadar
     end
   end
 
+  # The create_git_release_body method generates a changelog for a GitHub
+  # release by analyzing the git diff between the previous version and the
+  # current HEAD.
+  #
+  # It retrieves the log differences, fetches or uses default system and prompt
+  # templates, and utilizes an AI model to produce a formatted changelog entry.
+  #
+  # @return [ String ] the generated changelog content for the release body
   def create_git_release_body
     log_diff = version_log_diff(to_version: version)
     system   = xdg_config('release_system_prompt.txt', default_git_release_system_prompt)
@@ -620,26 +879,14 @@ class GemHadar
     ollama_generate(system:, prompt:)
   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('changelog')
-    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 github_release_task method defines a Rake task that creates a GitHub
+  # release for the current version.
+  #
+  # This method sets up a :github:release task that prompts the user to confirm
+  # publishing a release message on GitHub. It retrieves the GitHub API token
+  # from the environment, derives the repository owner and name from the git
+  # remote URL, generates a changelog using AI, and creates the release via the
+  # GitHub API.
   def github_release_task
     namespace :github do
       unless github_api_token = ENV['GITHUB_API_TOKEN'].full?
@@ -647,7 +894,7 @@ class GemHadar
         task :release
         return
       end
-      desc "Create a new GitHub release for the current version with a changelog"
+      desc "Create a new GitHub release for the current version with a AI-generated changelog"
       task :release do
         yes = ask?(
           "Do you want to publish a release message on github? (y/n%{default}) ",
@@ -681,6 +928,14 @@ class GemHadar
 
   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
+  # process of pushing changes and artifacts to remote repositories and package
+  # managers.
+  #
+  # This method sets up multiple subtasks including preparing the master
+  # branch, pushing version tags, pushing to gem repositories, and creating
+  # GitHub releases. It also includes a check for uncommitted changes before
+  # proceeding with the push operations.
   def push_task
     master_prepare_task
     version_push_task
@@ -695,10 +950,26 @@ class GemHadar
         exit 1
       end
     end
-    desc "Push master and version #{version} all git remotes: #{git_remotes * ' '}"
+    desc "Push all changes for version #{version} into the internets."
     task :push => push_task_dependencies
   end
 
+  # The release_task method defines a Rake task that orchestrates the complete
+  # release process for the gem.
+  #
+  # This method sets up a :release task that depends on the :push task,
+  # ensuring all necessary steps for publishing the gem are executed in
+  # sequence. It provides a convenient way to perform a full release workflow
+  # with a single command.
+  def release_task
+    desc "Release the new version #{version} for the gem #{name}."
+    task :release => :push
+  end
+
+  # The compile_task method sets up a Rake task to compile project extensions.
+  #
+  # This method creates a :compile task that iterates through the configured
+  # extensions and compiles them using the system's make command.
   def compile_task
     for file in extensions
       dir = File.dirname(file)
@@ -716,6 +987,16 @@ class GemHadar
     end
   end
 
+  # The rvm_task method creates a .rvmrc file that configures RVM to use the
+  # specified Ruby version and gemset for the project.
+  #
+  # This task generates a .rvmrc file in the project root directory with commands to:
+  # - Use the Ruby version specified by the rvm.use accessor
+  # - Create the gemset specified by the rvm.gemset accessor
+  # - Switch to using that gemset
+  #
+  # The generated file is written using the secure_write method to ensure
+  # proper file permissions.
   def rvm_task
     desc 'Create .rvmrc file'
     task :rvm do
@@ -729,15 +1010,55 @@ class GemHadar
     end
   end
 
+  def yard_doc_task
+    YARD::Rake::YardocTask.new(:yard_doc) do |t|
+      t.files = files.select { _1 =~ /\.rb\z/ }
+
+      output_dir = yard_dir
+      t.options = [ "--output-dir=#{output_dir}" ]
+
+      # Include private & protected methods in documentation
+      t.options << '--private' << '--protected'
+
+      # Handle readme if present
+      if readme && File.exist?(readme)
+        t.options << "--readme=#{readme}"
+      end
+
+      # Add additional documentation files
+      if doc_files&.any?
+        t.files.concat(doc_files.flatten)
+      end
+
+      # Add before hook for cleaning
+      t.before = proc {
+        clean output_dir
+        puts "Generating full documentation in #{output_dir}..."
+      }
+    end
+  end
+
+  # The yard_task method sets up and registers Rake tasks for generating and
+  # managing YARD documentation.
+  #
+  # It creates multiple subtasks under the :yard namespace, including tasks for
+  # creating private documentation, viewing the generated documentation,
+  # cleaning up documentation files, and listing undocumented elements.
+  # If YARD is not available, the method returns early without defining any tasks.
   def yard_task
     defined? YARD or return
+    yard_doc_task
+    desc 'Create yard documentation (including private)'
+    task :doc => :yard_doc
     namespace :yard do
       my_yard_dir = Pathname.new(yard_dir)
 
-      desc 'Create yard documentation (including private)'
-      task :private do
-        sh "yardoc -o #{my_yard_dir}"
-      end
+      task :private => :yard_doc
+
+      task :public => :yard_doc
+
+      desc 'Create yard documentation'
+      task :doc => :yard_doc
 
       desc 'View the yard documentation'
       task :view do
@@ -775,7 +1096,6 @@ class GemHadar
     gem_hadar_update_task
     gemspec_task
     gems_install_task
-    doc_task
     if test_dir
       test_task
       rcov_task
@@ -787,6 +1107,7 @@ class GemHadar
     version_bump_task
     version_tag_task
     push_task
+    release_task
     write_ignore_file
     write_gemfile
     if extensions.full?
@@ -798,6 +1119,31 @@ class GemHadar
     self
   end
 
+  # The edit_temp_file method creates a temporary file with the provided
+  # content, opens it in an editor for user modification, and returns the
+  # updated content.
+  #
+  # @param content [ String ] the initial content to write to the temporary file
+  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('changelog')
+    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
+
   # Generates a response from an AI model using the Ollama::Client.
   #
   # @param [String] system The system prompt for the AI model.
@@ -941,8 +1287,12 @@ class GemHadar
         s.rdoc_options << '--title' << "#{name.camelize} - #{summary}"
       end
       if readme
-        s.rdoc_options << '--main' << readme
-        s.extra_rdoc_files << readme
+        if File.exist?(readme)
+          s.rdoc_options << '--main' << readme
+          s.extra_rdoc_files << readme
+        else
+          warn "Add a #{readme} file to document your gem!"
+        end
       end
       doc_files.full? { |df| s.extra_rdoc_files.concat Array(df) }
     end
@@ -1045,6 +1395,11 @@ class GemHadar
     end
   end
 
+  # The version_untag method removes the 'v' prefix from a version tag string.
+  #
+  # @param version_tag [ String ] the version tag string that may start with 'v'
+  #
+  # @return [ String ] the version string with the 'v' prefix removed
   def version_untag(version_tag)
     version.sub(/\Av/, '')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem_hadar
 version: !ruby/object:Gem::Version
-  version: 1.25.0
+  version: 1.26.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.24'
+        version: '1.26'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.24'
+        version: '1.26'
 - !ruby/object:Gem::Dependency
   name: tins
   requirement: !ruby/object:Gem::Requirement