Document classes using puppet-strings

This doesn't convert all classes since the installer still relies on rdoc groups. However, not all classes are public and this converts what makes sense.
theforeman · Mar 15, 2020 · aecbe79 · aecbe79
1 parent 10467a2
commit aecbe79
Show file tree

Hide file tree

Showing 20 changed files with 107 additions and 54 deletions.
diff --git a/lib/puppet/functions/foreman_proxy/get_network_in_addr.rb b/lib/puppet/functions/foreman_proxy/get_network_in_addr.rb
@@ -1,8 +1,18 @@
-# Get the in-addr.arpa notation for the given IP address and a netmask
-
 require 'ipaddr'
 
+# @summary Get the domain holding the reverse DNS for a given IP address and a
+#   netmask
+# @example Get 2.0.192.in-addr-arpa
+#   foreman_proxy::get_network_in_addr('192.0.2.0', '255.255.255.0')
+# @example Get 168.192.in-addr-arpa
+#   foreman_proxy::get_network_in_addr('192.168.1.0', '255.255.254.0')
 Puppet::Functions.create_function(:'foreman_proxy::get_network_in_addr') do
+  # @param address
+  #   The network address
+  # @param netmask
+  #   The netmask
+  # @return The domain that holds the reverse DNS records for the given address
+  #   with the netmask
   dispatch :get_network_in_addr do
     required_param 'Stdlib::IP::Address::V4::Nosubnet', :address
     required_param 'Stdlib::IP::Address::V4::Nosubnet', :netmask

diff --git a/manifests/config.pp b/manifests/config.pp
@@ -1,4 +1,5 @@
-# Configure the foreman proxy
+# @summary Configure the foreman proxy
+# @api private
 class foreman_proxy::config {
 
   # Ensure SSL certs from the puppetmaster are available

diff --git a/manifests/feature.pp b/manifests/feature.pp
@@ -1,4 +1,4 @@
-# Declares that a smart proxy feature should be present and enabled
+# @summary Declare that a smart proxy feature should be present and enabled
 #
 # Used by foreman_proxy::register to specify that all of the expected features
 # should be present and enabled. Uses datacat to merge an array of features.

diff --git a/manifests/install.pp b/manifests/install.pp
@@ -1,4 +1,5 @@
-# Install the foreman proxy
+# @summary Install the foreman proxy
+# @api private
 class foreman_proxy::install {
   if $foreman_proxy::repo {
     foreman::repos { 'foreman_proxy':

diff --git a/manifests/params.pp b/manifests/params.pp
@@ -1,4 +1,5 @@
-# The default parameters for the foreman proxy
+# @summary The default parameters for the foreman proxy
+# @api private
 class foreman_proxy::params {
 
   $lower_fqdn = downcase($::fqdn)

diff --git a/manifests/plugin.pp b/manifests/plugin.pp
@@ -1,4 +1,11 @@
-# Installs a smart proxy plugin package
+# @summary Install a smart proxy plugin package
+#
+# @param version
+#   The package to ensure. Can be a installed, absent or a specific version
+#
+# @param package
+#   The package to install. Underscores are replaced with dashes on Debian
+#
 define foreman_proxy::plugin(
   $version = $foreman_proxy::plugin_version,
   $package = "${foreman_proxy::plugin_prefix}${title}",

diff --git a/manifests/plugin/ansible/params.pp b/manifests/plugin/ansible/params.pp
@@ -1,4 +1,5 @@
-# Ansible proxy default parameters
+# @summary Ansible proxy default parameters
+# @api private
 class foreman_proxy::plugin::ansible::params {
   $enabled     = true
   $listen_on   = 'https'

diff --git a/manifests/plugin/discovery.pp b/manifests/plugin/discovery.pp
@@ -1,16 +1,16 @@
-# = Foreman Proxy Discovery plugin
+# @summary Install the discovery plugin and images on smart proxies
 #
-# This class installs discovery plugin and images on smart proxys
+# @param install_images
+#   should the discovery image be downloaded and extracted
 #
-# === Parameters:
+# @param tftp_root
+#   tftp root to install image into
 #
-# $install_images::  should the discovery image be downloaded and extracted
+# @param source_url
+#   source URL to download from
 #
-# $tftp_root::       tftp root to install image into
-#
-# $source_url::      source URL to download from
-#
-# $image_name::      tarball with images
+# @param image_name
+#   tarball with images
 #
 class foreman_proxy::plugin::discovery (
   Boolean $install_images = $::foreman_proxy::plugin::discovery::params::install_images,

diff --git a/manifests/plugin/dynflow/params.pp b/manifests/plugin/dynflow/params.pp
@@ -1,4 +1,5 @@
-# Default parameters for the Dynflow smart proxy plugin
+# @summary Default parameters for the Dynflow smart proxy plugin
+# @api private
 class foreman_proxy::plugin::dynflow::params {
   $enabled               = true
   $listen_on             = 'https'

diff --git a/manifests/plugin/monitoring/icingadirector/params.pp b/manifests/plugin/monitoring/icingadirector/params.pp
@@ -1,3 +1,5 @@
+# @summary Defaults for the icingadirector provider to the monitoring plugin
+# @api private
 class foreman_proxy::plugin::monitoring::icingadirector::params {
   $enabled = true
   $director_url = "https://${::fqdn}/icingaweb2/director"

diff --git a/manifests/proxydhcp.pp b/manifests/proxydhcp.pp
@@ -1,4 +1,5 @@
-# Configure the DHCP component
+# @summary Configure the ISC DHCP service
+# @api private
 class foreman_proxy::proxydhcp {
   # puppet fact names are converted from ethX.X and ethX:X to ethX_X
   # so for alias and vlan interfaces we have to modify the name accordingly

diff --git a/manifests/proxydns.pp b/manifests/proxydns.pp
@@ -1,17 +1,22 @@
-# Configure the DNS component
+# @summary Configure the ISC named service
 #
-# $forwarders:: The DNS forwarders to use
+# @param forwarders
+#   The DNS forwarders to use
 #
-# $interface:: The interface to use for fact determination. By default the IP
-#              is used to create an A record in the forward zone and determine
-#              the reverse DNS zone(s).
+# @param interface
+#   The interface to use for fact determination. By default the IP is used to
+#   create an A record in the forward zone and determine the reverse DNS
+#   zone(s).
 #
-# $forward_zone:: The forward DNS zone name
+# @param forward_zone
+#   The forward DNS zone name
 #
-# $reverse_zone:: The reverse DNS zone name
+# @param reverse_zone
+#   The reverse DNS zone name
 #
-# $soa:: The hostname to use in the SOA record. Also used to create a forward
-#        DNS entry.
+# @param soa
+#   The hostname to use in the SOA record. Also used to create a forward DNS
+#   entry.
 #
 class foreman_proxy::proxydns(
   $forwarders = $::foreman_proxy::dns_forwarders,

diff --git a/manifests/register.pp b/manifests/register.pp
@@ -1,4 +1,5 @@
-# Register the foreman proxy
+# @summary Register the foreman proxy
+# @api private
 class foreman_proxy::register {
   if $foreman_proxy::register_in_foreman {
     foreman_smartproxy { $foreman_proxy::registered_name:

diff --git a/manifests/remote_file.pp b/manifests/remote_file.pp
@@ -1,4 +1,5 @@
-# Downloads a file from a URL to a local file given by the title
+# @summary Downloads a file from a URL to a local file given by the title
+# @api private
 define foreman_proxy::remote_file(
   $remote_location,
   $mode='0644',

diff --git a/manifests/service.pp b/manifests/service.pp
@@ -1,4 +1,5 @@
-# Set up the foreman service
+# @summary Set up the foreman service
+# @api private
 class foreman_proxy::service {
 
   service { 'foreman-proxy':

diff --git a/manifests/settings_file.pp b/manifests/settings_file.pp
@@ -1,40 +1,44 @@
+# @summary Generate a settings file for a module
 #
-# == Define: foreman_proxy::settings_file
+# @param ensure
+#   Whether the config file should be a file or absent
 #
-# Generates a settings file for a module
+# @param module
+#   Whether the config file is a proxy module or not
 #
-# == Parameters
+# @param enabled
+#   If module is enabled or not
 #
-# $module::        Whether the config file is a proxy module or not
+# @param listen_on
+#   Whether the module listens on https, http, or both
 #
-# $enabled::       If module is enabled or not
+# @param path
+#   Path to module's settings file
 #
-# $listen_on::     Whether the module listens on https, http, or both
+# @param template_path
+#   Location of the template used to generate module's settings
 #
-# $path::          Path to module's settings file, by default
-#                  '/etc/foreman-proxy/settings.d/<module name>.yml
+# @param owner
+#   Settings file's owner
 #
-# $template_path:: Location of the template used to generate module's settings
+# @param group
+#   Settings file's group
 #
-# $owner::         Settings file's owner
+# @param mode
+#   Settings file's mode
 #
-# $group::         Settings file's group
-#
-# $mode::          Settings file's mode
-#
-# $feature::       Feature name advertised by proxy module
-#                  If set, foreman_proxy::register will validate the feature name is loaded and advertised.
-#
-# $ensure::        Whether the config file should be a file or absent
+# @param feature
+#   Feature name advertised by proxy module. If set, foreman_proxy::register
+#   will validate the feature name is loaded and advertised.
 #
 define foreman_proxy::settings_file (
   Enum['file', 'absent'] $ensure = 'file',
   Boolean $module = true,
   Boolean $enabled = true,
   Foreman_proxy::ListenOn $listen_on = 'https',
-  Stdlib::Absolutepath $path = "${::foreman_proxy::etc}/foreman-proxy/settings.d/${title}.yml",
+  Stdlib::Absolutepath $path = "${foreman_proxy::etc}/foreman-proxy/settings.d/${title}.yml",
   String $owner = 'root',
-  String $group = $::foreman_proxy::user,
+  String $group = $foreman_proxy::user,
   Stdlib::Filemode $mode = '0640',
   String $template_path = "foreman_proxy/${title}.yml.erb",
   Optional[String] $feature = undef,

diff --git a/manifests/tftp.pp b/manifests/tftp.pp
@@ -1,4 +1,5 @@
-# Set up the tftp component
+# @summary Set up the tftp service
+# @api private
 class foreman_proxy::tftp (
   $user = $::foreman_proxy::user,
   $root = $::foreman_proxy::tftp_root,

diff --git a/manifests/tftp/netboot.pp b/manifests/tftp/netboot.pp
@@ -1,4 +1,17 @@
-# Netboot support for TFTP. Installs the files so other systems can netboot.
+# @summary Netboot support for TFTP. Installs the files so other systems can netboot.
+#
+# @param packages
+#   The packages to install
+#
+# @param grub_installation_type
+#   The method to configure grub
+#
+# @param grub_modules
+#   The grub modules to enable
+#
+# @param root
+#   The root directory to use for grub
+#
 class foreman_proxy::tftp::netboot (
   Array[String] $packages = $::foreman_proxy::tftp::netboot::params::packages,
   Enum['redhat_exec', 'redhat', 'redhat_old', 'debian', 'none'] $grub_installation_type = $::foreman_proxy::tftp::netboot::params::grub_installation_type,

diff --git a/manifests/tftp/netboot/params.pp b/manifests/tftp/netboot/params.pp
@@ -1,4 +1,5 @@
-# Parameters for EFI
+# @summary Parameters for EFI
+# @api private
 class foreman_proxy::tftp::netboot::params {
   # taken from https://anonscm.debian.org/cgit/pkg-grub/grub.git/tree/debian/build-efi-images + regexp
   $grub_modules = 'all_video boot btrfs cat chain configfile echo efifwsetup efinet ext2 fat font gettext gfxmenu gfxterm gfxterm_background gzio halt hfsplus iso9660 jpeg keystatus loadenv linux lsefi lsefimmap lsefisystab lssal memdisk minicmd normal part_apple part_msdos part_gpt password_pbkdf2 png reboot search search_fs_uuid search_fs_file search_label sleep test true video zfs zfscrypt zfsinfo linuxefi lvm mdraid09 mdraid1x raid5rec raid6rec tftp regexp'

diff --git a/types/listenon.pp b/types/listenon.pp
@@ -1 +1,2 @@
+# The possible protocols a smart proxy module can listen on
 type Foreman_proxy::ListenOn = Enum['http', 'https', 'both']