Hier is een voorbeeld van Ruby-code die gebruikmaakt van de gem 'yard' om automatisch documentatie te genereren voor je codebase, specifiek voor de mappen app/models en app/controllers. Deze setup zorgt voor gedetailleerde commentaar, functiebeschrijvingen en voorbeelden, en exporteert de documentatie naar HTML. De code is modulair en makkelijk uit te breiden. Stap 1: Installeer YARD Voer in je terminal uit: ```bash gem install yard ``` Stap 2: Maak een Ruby-script voor het genereren van documentatie ```ruby # generate_docs.rb require 'yard' # Configuratie van YARD YARD::CLI::Yardoc.run([ '--output-dir', 'doc', '--markup', 'markdown', '--readme', 'README.md', # Optioneel: voeg een README toe '--plugin', 'yard', # Zorg dat de plugin geladen wordt 'app/models', # Documenteer models 'app/controllers' # Documenteer controllers ]) # Optioneel: voeg extra configuraties toe, zoals het genereren van een index of custom templates ``` Stap 3: Voeg Javadoc-achtige commentaar toe aan je code Voorbeeld van commentaar in je Ruby-bestanden: ```ruby # app/models/user.rb # User-model dat gebruikers van de applicatie representeert. # # @example # user = User.new(name: 'Jan') # puts user.name class User # De naam van de gebruiker. # # @return [String] attr_accessor :name # Maakt een nieuwe gebruiker aan. # # @param [String] name De naam van de gebruiker. def initialize(name) @name = name end # Geeft een begroeting voor de gebruiker. # # @return [String] Een begroetingsbericht. # # @example # user = User.new('Jan') # puts user.greet # => "Hallo, Jan!" def greet "Hallo, #{name}!" end end ``` Stap 4: Uitbreidingen en integratie - Voor meer maatwerk kun je templates aanpassen of plugins toevoegen. - Je kunt de documentatie automatisch genereren met een buildscript of CI/CD-pipeline. - Voor complexere setups kun je de YARD API gebruiken om aangepaste scripts te schrijven die bijvoorbeeld alleen bepaalde modules documenteren. Door dit script te gebruiken en je code te voorzien van goede commentaar, genereer je makkelijk uitgebreide HTML-documentatie die je kunt integreren in je project. Mocht je meer specifieke wensen hebben of hulp nodig bij het aanpassen, laat het gerust weten!

Ik zal je helpen een Ruby script te schrijven voor automatische documentatiegeneratie. Hier is een complete oplossing: ```ruby # documentation_generator.rb require 'yard' require 'fileutils' class DocumentationGenerator attr_reader :source_dirs, :output_dir, :yardoc def initialize(source_dirs: ['app/models', 'app/controllers'], output_dir: 'doc') @source_dirs = Array(source_dirs) @output_dir = output_dir @yardoc = YARD::CLI::Yardoc.new end # Configureer YARD opties voor HTML output def configure_yard yardoc.options.update({ output: output_dir, format: :html, embed_mixins: true, one_file: false, verbose: true, markup: :markdown, templates: [:default] }) end # Genereer documentatie def generate_documentation puts "Documentatie genereren voor: #{source_dirs.join(', ')}" configure_yard create_output_directory # Verzamel alle Ruby bestanden files = collect_ruby_files if files.empty? puts "Geen Ruby bestanden gevonden in de opgegeven mappen." return false end puts "Gevonden #{files.size} Ruby bestanden om te documenteren..." # Genereer documentatie met YARD begin YARD::Registry.clear yardoc.run(*files) puts "Documentatie succesvol gegenereerd in: #{output_dir}" true rescue StandardError => e puts "Fout bij genereren documentatie: #{e.message}" false end end # Verzamel alle .rb bestanden uit de source directories def collect_ruby_files files = [] source_dirs.each do |dir| if File.directory?(dir) files.concat(Dir.glob(File.join(dir, '**', '*.rb'))) else puts "Waarschuwing: Directory #{dir} bestaat niet" end end files end # Maak output directory aan als deze niet bestaat def create_output_directory FileUtils.mkdir_p(output_dir) unless File.directory?(output_dir) end # Voeg custom templates toe (uitbreidbaar) def add_custom_template(template_path) yardoc.options[:template] = template_path end # Configureer extra opties def set_option(option, value) yardoc.options[option] = value end end # Voorbeeld gebruik: if __FILE__ == $0 generator = DocumentationGenerator.new( source_dirs: ['app/models', 'app/controllers'], output_dir: 'public/docs' ) # Optionele extra configuratie generator.set_option(:title, "Mijn Applicatie Documentatie") if generator.generate_documentation puts "Open documentatie: open #{generator.output_dir}/index.html" else puts "Documentatie genereren mislukt" exit 1 end end ``` ## Gemfile toevoegen: ```ruby # Gemfile source 'https://rubygems.org' gem 'yard', '~> 0.9.28' gem 'redcarpet', '~> 3.5' # Voor Markdown ondersteuning ``` ## Installatie en gebruik: 1. **Installatie:** ```bash bundle install ``` 2. **Uitvoeren:** ```bash ruby documentation_generator.rb ``` 3. **Als Rake task (optioneel):** ```ruby # Rakefile require_relative 'documentation_generator' desc "Genereer documentatie" task :docs do generator = DocumentationGenerator.new generator.generate_documentation end ``` ## Voorbeeld van goede code documentatie: ```ruby # app/models/user.rb class User < ApplicationRecord # Geeft de volledige naam van de gebruiker terug # # @example # user = User.new(first_name: "Jan", last_name: "Jansen") # user.full_name # => "Jan Jansen" # # @return [String] De volledige naam def full_name "#{first_name} #{last_name}" end # Controleert of de gebruiker admin rechten heeft # # @return [Boolean] true als gebruiker admin is def admin? role == 'admin' end end ``` ## Uitbreidingsmogelijkheden: 1. **Custom templates:** ```ruby generator.add_custom_template('mijn_template') ``` 2. **Extra directories:** ```ruby generator = DocumentationGenerator.new( source_dirs: ['app/models', 'app/controllers', 'lib'], output_dir: 'docs' ) ``` 3. **CI/CD integratie:** Voeg toe aan je GitHub Actions of GitLab CI configuratie. Deze oplossing gebruikt YARD, de standaard Ruby documentatie tool, en is volledig uitbreidbaar en integreert eenvoudig met bestaande tools.