add rdoc documentation to ruby code (#3)

README.md

@@ -7,7 +7,7 @@
 
 ## Table of Contents
 
-- [Description](#description)
+- [Module Description](#module-description)
 - [Features](#features)
 - [Setup](#setup)
   * [OPNsense firewall](#opnsense-firewall)

lib/puppet/provider/opnsense_device/opnsense_device.rb

@@ -7,18 +7,25 @@
 
 # Implementation for the opnsense_device type using the Resource API.
 class Puppet::Provider::OpnsenseDevice::OpnsenseDevice < Puppet::Provider::OpnsenseProvider
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [Array<Hash<Symbol>>] filter
+  # @return [Array<Hash<Symbol>>]
   def get(_context, filter)
     device_names = get_device_names_by_filter(filter)
     _get_devices(device_names)
   end
 
+  # @param [Array<Hash<Symbol>>] filter
+  # @return [Array<Hash<Symbol>>, Array<String>]
   def get_device_names_by_filter(filter)
     if filter.empty?
       return get_configured_devices
     end
     filter
   end
 
+  # @param [Array<String>] device_names
+  # @return [Array<Hash<Symbol>>]
   def _get_devices(device_names)
     result = []
     device_names.each do |device_name|
@@ -31,6 +38,9 @@ def _get_devices(device_names)
     result
   end
 
+  # @param [String] device_name
+  # @param [Array<Hash<String>>] data
+  # @return [Hash{Symbol->Hash<String>}]
   def _create_opnsense_device(device_name, data)
     {
       ensure: 'present',
@@ -44,22 +54,36 @@ def _create_opnsense_device(device_name, data)
     }
   end
 
+  # @param [String] path
+  # @return [Psych::Exception, nil]
   def _read_yaml(path)
     YAML.safe_load(File.read(path))
   end
 
+  # @param [String] pw
+  # @return [Puppet::Provider::OpnsenseSensitive]
   def _gen_pw(pw)
     Puppet::Provider::OpnsenseSensitive.new(pw)
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] name
+  # @param [Hash<Symbol>] should
+  # @return [File]
   def create(_context, name, should)
     _write_config(name, should)
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] name
+  # @param [Hash<Symbol>] should
   def update(_context, name, should)
     _write_config(name, should)
   end
 
+  # @param [String] name
+  # @param [Hash<Symbol>] should
+  # @return [File]
   def _write_config(name, should)
     basedir = get_config_basedir
     _ensure_dir(basedir)
@@ -75,26 +99,38 @@ def _write_config(name, should)
     _write_yaml(config_path, yaml_data)
   end
 
+  # @param [String] path
+  # @param [Integer] mode
+  # @return [Integer]
   def _ensure_dir(path, mode = 0o700)
     Dir.mkdir(path, mode) unless File.exist?(path)
   end
 
+  # @param [Puppet::Provider::OpnsenseSensitive] sensitive
+  # @return [String]
   def _extract_pw(sensitive)
     sensitive.unwrap
   end
 
+  # @param [String] path
+  # @param [Hash] data
+  # @param [Integer] mode
   def _write_yaml(path, data, mode = 0o600)
     File.open(path, 'w') do |file|
       file.write(YAML.dump(data))
       file.chmod(mode)
     end
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] name
   def delete(_context, name)
     path = get_config_path(name)
     FileUtils.rm(path, force: true)
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [Hash] resources
   def canonicalize(_context, resources)
     resources.each do |r|
       if r.key?(:api_secret) && r[:api_secret].is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive)

lib/puppet/provider/opnsense_firewall_alias/opnsense_firewall_alias.rb

@@ -5,14 +5,18 @@
 
 # Implementation for the opnsense_firewall_alias type using the Resource API.
 class Puppet::Provider::OpnsenseFirewallAlias::OpnsenseFirewallAlias < Puppet::Provider::OpnsenseProvider
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [Array<Hash<Symbol>>] filter
+  # @return [Array<Hash<Symbol>>]
   def get(_context, filter)
     device_names = get_device_names_by_filter(filter)
     _get_firewall_aliases_from_devices(device_names)
   end
 
+  # @param [Array<String>] devices
+  # @return [Array<Hash<Symbol>>]
   def _get_firewall_aliases_from_devices(devices)
     result = []
-
     devices.each do |device|
       aliases = _aliases_list(device)
       aliases.each do |fw_alias|
@@ -34,23 +38,36 @@ def _get_firewall_aliases_from_devices(devices)
     result
   end
 
+  # @param [String] device_name
+  # @return [Array]
   def _aliases_list(device_name)
     json_output = opn_cli_base_cmd(device_name, ['firewall', 'alias', 'list', '-o', 'json'])
     JSON.parse(json_output)
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] _name
+  # @param [Hash<Symbol>] should
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def create(_context, _name, should)
     args = _get_command_args('create', should)
     device_name = should[:device].to_s
     opn_cli_base_cmd(device_name, args)
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] _name
+  # @param [Hash<Symbol>] should
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def update(_context, _name, should)
     args = _get_command_args('update', should)
     device_name = should[:device].to_s
     opn_cli_base_cmd(device_name, args)
   end
 
+  # @param [Integer] mode
+  # @param [Hash<Symbol>] should
+  # @return [Array<String>]
   def _get_command_args(mode, should)
     args = ['firewall', 'alias', mode, should[:name]]
     args.push('-t', should[:type])
@@ -66,6 +83,9 @@ def _get_command_args(mode, should)
     args
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] name
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def delete(_context, name)
     alias_name = name.fetch(:name).to_s
     device_name = name.fetch(:device).to_s

lib/puppet/provider/opnsense_plugin/opnsense_plugin.rb

@@ -4,15 +4,20 @@
 
 # Implementation for the opnsense_plugin type using the Resource API.
 class Puppet::Provider::OpnsensePlugin::OpnsensePlugin < Puppet::Provider::OpnsenseProvider
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [Array<Hash<Symbol>>] filter
+  # @return [Array<Hash<Symbol>>]
   def get(_context, filter)
     device_names = get_device_names_by_filter(filter)
-    get_plugins_from_devices(device_names)
+    _get_plugins_from_devices(device_names)
   end
 
-  def get_plugins_from_devices(devices)
+  # @param [Array<String>] devices
+  # @return [Array<Hash<Symbol>>]
+  def _get_plugins_from_devices(devices)
     result = []
     devices.each do |device|
-      plugins = plugin_list(device)
+      plugins = _plugin_list(device)
       plugins.each do |plugin|
         result.push(
             title: plugin + '@' + device,
@@ -25,30 +30,51 @@ def get_plugins_from_devices(devices)
     result
   end
 
-  def plugin_list(device_name)
+  # @param [String] device_name
+  # @return [Array<String>]
+  def _plugin_list(device_name)
     result = opn_cli_base_cmd(device_name, ['plugin', 'installed', '-c', 'name'])
     result.split("\n")
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] _name
+  # @param [Hash<Symbol>] should
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def create(_context, _name, should)
-    plugin_install(should[:device].to_s, should[:name].to_s)
+    _plugin_install(should[:device].to_s, should[:name].to_s)
   end
 
-  def plugin_install(device_name, plugin_name)
-    opn_cli_base_cmd(device_name, ['plugin', 'install', plugin_name.to_s])
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] _name
+  # @param [Hash<Symbol>] should
+  # @return [Puppet::Util::Execution::ProcessOutput]
+  def update(_context, _name, should)
+    _plugin_install(should[:device].to_s, should[:name].to_s)
   end
 
-  def update(_context, _name, should)
-    plugin_install(should[:device].to_s, should[:name].to_s)
+  # @param [String] device_name
+  # @param [String] plugin_name
+  # @return [Puppet::Util::Execution::ProcessOutput]
+  def _plugin_install(device_name, plugin_name)
+    opn_cli_base_cmd(device_name, ['plugin', 'install', plugin_name.to_s])
   end
 
+  # @param [Puppet::ResourceApi::BaseContext] _context
+  # @param [String] name
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def delete(_context, name)
     plugin_name = name.fetch(:name).to_s
     device = name.fetch(:device).to_s
-    plugin_uninstall(device, plugin_name)
+    _plugin_uninstall(device, plugin_name)
   end
 
-  def plugin_uninstall(device_name, plugin_name)
+  # @param [String] device_name
+  # @param [String] plugin_name
+  # @return [Puppet::Util::Execution::ProcessOutput]
+  def _plugin_uninstall(device_name, plugin_name)
     opn_cli_base_cmd(device_name, ['plugin', 'uninstall', plugin_name.to_s])
   end
+
+  private :_get_plugins_from_devices, :_plugin_list, :_plugin_install, :_plugin_uninstall
 end

lib/puppet/provider/opnsense_provider.rb

@@ -3,12 +3,16 @@
 
 # A base provider for all opnsense providers
 class Puppet::Provider::OpnsenseProvider < Puppet::ResourceApi::SimpleProvider
+  # @return [void]
   def initialize
     @config_basedir = '~/.puppet-opnsense'
     @config_suffix = '-config.yaml'
     super
   end
 
+  # @param [String] device_name
+  # @param [Array] args
+  # @return [Puppet::Util::Execution::ProcessOutput]
   def opn_cli_base_cmd(device_name, *args)
     config_path = get_config_path(device_name)
     args.unshift(
@@ -19,10 +23,13 @@ def opn_cli_base_cmd(device_name, *args)
     Puppet::Util::Execution.execute(args, failonfail: true, custom_environment: { 'LC_ALL' => 'en_US.utf8' })
   end
 
+  # @param [String] device_name
+  # @return [String]
   def get_config_path(device_name)
     File.join(get_config_basedir.to_s, "#{File.basename(device_name)}#{_get_suffix}")
   end
 
+  # @return [Array]
   def get_configured_devices
     devices = []
     Dir.glob(_get_config_glob_pattern).each do |path|
@@ -32,18 +39,23 @@ def get_configured_devices
     devices
   end
 
+  # @return [String]
   def _get_config_glob_pattern
     "#{get_config_basedir}/*#{_get_suffix}"
   end
 
+  # @return [String]
   def _get_suffix
     @config_suffix
   end
 
+  # @return [String]
   def get_config_basedir
     File.expand_path(@config_basedir)
   end
 
+  # @param [String, Integer, Boolean] value
+  # @return [FalseClass, TrueClass]
   def bool_from_value(value)
     case value
     when true, 'true', 1, '1' then
@@ -55,6 +67,8 @@ def bool_from_value(value)
     end
   end
 
+  # @param [Array<Hash<Symbol>>] filter
+  # @return [Array]
   def get_device_names_by_filter(filter)
     filter.empty? ? get_configured_devices : filter.map { |item| item[:device] }.compact.uniq
   end

lib/puppet/provider/opnsense_sensitive.rb

@@ -1,6 +1,8 @@
 # A Puppet Language type that makes the OpnsenseSensitive Type comparable
 #
 class Puppet::Provider::OpnsenseSensitive < Puppet::Pops::Types::PSensitiveType::Sensitive
+  # @param [Puppet::Pops::Types::PSensitiveType::Sensitive] other
+  # @return [TrueClass]
   def ==(other)
     return true if other.is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive) && unwrap == other.unwrap
   end