From 5848705cf0648c664d3dc8c617a2b9524d5a5636 Mon Sep 17 00:00:00 2001 From: Brian Durand Date: Wed, 7 Jan 2026 09:13:23 -0800 Subject: [PATCH] Add task to remove yard docs --- CHANGELOG.md | 2 +- README.md | 4 +- .../documentation/source_file.rb | 7 ++ lib/tasks/support_table_data.rake | 64 ++++++++++++------- .../documentation/source_file_spec.rb | 34 ++++++++++ spec/tasks_spec.rb | 42 ++++++++++-- 6 files changed, 121 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c597bb5..a3c6944 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - The default data directory in a Rails application can be set with the `config.support_table.data_directory` option in the Rails application configuration. -- Added rake task `support_table_data:add_yard_docs` for Rails applications that will add YARD documentation to support table models for the named instance helpers. There is also a task `support_table_data:verify_yard_docs` that can be used in a build pipeline to verify that the documentation is up to date. +- Added rake task `support_table_data:yard_docs:add` for Rails applications that will add YARD documentation to support table models for the named instance helpers. There is also a task `support_table_data:yard_docs:verify` that can be used in a build pipeline to verify that the documentation is up to date. You can also remove the documentation with the `support_table_data:yard_docs:remove` task. - The data synchronization task is now automatically attached to several Rails tasks: `db:seed`, `db:seed:replant`, `db:prepare`, `db:test:prepare`, `db:fixtures:load`. Support tables will be synced after running any of these tasks. This can be disabled by setting `config.support_table.auto_sync = false` in the Rails application configuration. ### Changed diff --git a/README.md b/README.md index 91e29b2..384356b 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ completed: #### Documenting Named Instance Helpers -In a Rails application, you can add YARD documentation for the named instance helpers by running the rake task `support_table_data:add_yard_docs`. This will add YARD comments to your model classes for each of the named instance helper methods defined on the model. Adding this documentation will help IDEs provide better code completion and inline documentation for the helper methods and expose the methods to AI agents. +In a Rails application, you can add YARD documentation for the named instance helpers by running the rake task `support_table_data:yard_docs:add`. This will add YARD comments to your model classes for each of the named instance helper methods defined on the model. Adding this documentation will help IDEs provide better code completion and inline documentation for the helper methods and expose the methods to AI agents. The default behavior is to add the documentation comments at the end of the model class by reopening the class definition. If you prefer to have the documentation comments appear elsewhere in the file, you can add the following markers to your model class and the YARD documentation will be inserted between these markers. @@ -196,7 +196,7 @@ The default behavior is to add the documentation comments at the end of the mode # End YARD docs for support_table_data ``` -A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date. You can run the rake task `support_table_data:verify_yard_docs` to do this. It will exit with an error if any models do not have up to date documentation. +A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date. You can run the rake task `support_table_data:yard_docs:verify` to do this. It will exit with an error if any models do not have up to date documentation. ### Caching diff --git a/lib/support_table_data/documentation/source_file.rb b/lib/support_table_data/documentation/source_file.rb index 186b376..29f27f1 100644 --- a/lib/support_table_data/documentation/source_file.rb +++ b/lib/support_table_data/documentation/source_file.rb @@ -78,6 +78,13 @@ def yard_docs_up_to_date? source == source_with_yard_docs end + # Check if the source file has any YARD documentation added by support_table_data. + # + # @return [Boolean] + def has_yard_docs? + source.match?(YARD_COMMENT_REGEX) + end + private def trailing_newline diff --git a/lib/tasks/support_table_data.rake b/lib/tasks/support_table_data.rake index 5a5710f..3968c37 100644 --- a/lib/tasks/support_table_data.rake +++ b/lib/tasks/support_table_data.rake @@ -23,39 +23,55 @@ namespace :support_table_data do end end - desc "Adds YARD documentation comments to models to document the named instance methods." - task add_yard_docs: :environment do - require_relative "../support_table_data/documentation" - require_relative "utils" + namespace :yard_docs do + desc "Adds YARD documentation comments to models to document the named instance methods." + task add: :environment do + require_relative "../support_table_data/documentation" + require_relative "utils" - SupportTableData::Tasks::Utils.eager_load! - SupportTableData::Tasks::Utils.support_table_sources.each do |source_file| - next if source_file.yard_docs_up_to_date? + SupportTableData::Tasks::Utils.eager_load! + SupportTableData::Tasks::Utils.support_table_sources.each do |source_file| + next if source_file.yard_docs_up_to_date? - source_file.path.write(source_file.source_with_yard_docs) - puts "Added YARD documentation to #{source_file.klass.name}." + source_file.path.write(source_file.source_with_yard_docs) + puts "Added YARD documentation to #{source_file.klass.name}." + end end - end - desc "Verify that all the support table models have up to date YARD documentation for named instance methods." - task verify_yard_docs: :environment do - require_relative "../support_table_data/documentation" - require_relative "utils" + desc "Removes YARD documentation comments added by support_table_data from models." + task remove: :environment do + require_relative "../support_table_data/documentation" + require_relative "utils" - SupportTableData::Tasks::Utils.eager_load! + SupportTableData::Tasks::Utils.eager_load! + SupportTableData::Tasks::Utils.support_table_sources.each do |source_file| + next unless source_file.has_yard_docs? - all_up_to_date = true - SupportTableData::Tasks::Utils.support_table_sources.each do |source_file| - unless source_file.yard_docs_up_to_date? - puts "YARD documentation is not up to date for #{source_file.klass.name}." - all_up_to_date = false + source_file.path.write(source_file.source_without_yard_docs) + puts "Removed YARD documentation from #{source_file.klass.name}." end end - if all_up_to_date - puts "All support table models have up to date YARD documentation." - else - raise + desc "Verify that all the support table models have up to date YARD documentation for named instance methods." + task verify: :environment do + require_relative "../support_table_data/documentation" + require_relative "utils" + + SupportTableData::Tasks::Utils.eager_load! + + all_up_to_date = true + SupportTableData::Tasks::Utils.support_table_sources.each do |source_file| + unless source_file.yard_docs_up_to_date? + puts "YARD documentation is not up to date for #{source_file.klass.name}." + all_up_to_date = false + end + end + + if all_up_to_date + puts "All support table models have up to date YARD documentation." + else + raise "Run bundle exec rails support_table_data:yard_docs:add to update the documentation." + end end end end diff --git a/spec/support_table_data/documentation/source_file_spec.rb b/spec/support_table_data/documentation/source_file_spec.rb index 075c165..4083f5a 100644 --- a/spec/support_table_data/documentation/source_file_spec.rb +++ b/spec/support_table_data/documentation/source_file_spec.rb @@ -229,4 +229,38 @@ class Color expect(source_file.yard_docs_up_to_date?).to be false end end + + describe "#has_yard_docs?" do + it "returns true when YARD docs are present" do + source_with_docs = <<~RUBY + class Color < ActiveRecord::Base + include SupportTableData + + class Color + # Begin YARD docs for support_table_data + # Some YARD docs + # End YARD docs for support_table_data + end + end + RUBY + + source_file = SupportTableData::Documentation::SourceFile.new(Color, color_path) + allow(source_file).to receive(:source).and_return(source_with_docs) + + expect(source_file.has_yard_docs?).to be true + end + + it "returns false when YARD docs are absent" do + source_without_docs = <<~RUBY + class Color < ActiveRecord::Base + include SupportTableData + end + RUBY + + source_file = SupportTableData::Documentation::SourceFile.new(Color, color_path) + allow(source_file).to receive(:source).and_return(source_without_docs) + + expect(source_file.has_yard_docs?).to be false + end + end end diff --git a/spec/tasks_spec.rb b/spec/tasks_spec.rb index b15fc40..14f7abf 100644 --- a/spec/tasks_spec.rb +++ b/spec/tasks_spec.rb @@ -32,7 +32,7 @@ end end - describe "add_yard_docs" do + describe "yard_docs:add" do it "adds YARD documentation to models with named instances" do require_relative "../lib/support_table_data/documentation" require_relative "../lib/tasks/utils" @@ -47,7 +47,7 @@ end # Run the task - Rake.application.invoke_task "support_table_data:add_yard_docs" + Rake.application.invoke_task "support_table_data:yard_docs:add" # Verify that at least one model had documentation added expect(written_files).not_to be_empty @@ -61,7 +61,39 @@ end end - describe "verify_yard_docs" do + describe "yard_docs:remove" do + it "removes YARD documentation from models" do + require_relative "../lib/support_table_data/documentation" + require_relative "../lib/tasks/utils" + + # Mock stdout to capture puts + allow($stdout).to receive(:puts) + + # Track which files would be written to + written_files = [] + allow_any_instance_of(Pathname).to receive(:write) do |instance, content| + written_files << {path: instance.to_s, content: content} + end + + # Mock that files have YARD docs + allow_any_instance_of(SupportTableData::Documentation::SourceFile) + .to receive(:has_yard_docs?).and_return(true) + + # Run the task + Rake.application.invoke_task "support_table_data:yard_docs:remove" + + # Verify that files were written to + expect(written_files).not_to be_empty + expect($stdout).to have_received(:puts).at_least(:once) + + # Verify the written content doesn't include YARD docs (check one example) + color_write = written_files.find { |f| f[:path].include?("color.rb") } + expect(color_write).not_to be_nil + expect(color_write[:content]).not_to include("# Begin YARD docs for support_table_data") + end + end + + describe "yard_docs:verify" do it "verifies YARD documentation is up to date" do require_relative "../lib/support_table_data/documentation" require_relative "../lib/tasks/utils" @@ -71,7 +103,7 @@ .to receive(:yard_docs_up_to_date?).and_return(true) # Run the task - Rake.application.invoke_task "support_table_data:verify_yard_docs" + Rake.application.invoke_task "support_table_data:yard_docs:verify" # Verify output indicates all docs are up to date expect($stdout).to have_received(:puts).with("All support table models have up to date YARD documentation.") @@ -87,7 +119,7 @@ # Run the task and expect an error expect { - Rake.application.invoke_task "support_table_data:verify_yard_docs" + Rake.application.invoke_task "support_table_data:yard_docs:verify" }.to raise_error(RuntimeError) # Verify output indicates which docs are out of date