Merge pull request #211 from puppetlabs/reference.md

Add auto-generated REFERENCE.md documentation

Author: reidmv

REFERENCE.md

@@ -1,3 +1,4 @@
+# @summary Assert that the architecture given is a supported one
 function peadm::assert_supported_architecture (
   TargetSpec                 $primary_host,
   Variant[TargetSpec, Undef] $replica_host = undef,

functions/assert_supported_architecture.pp

@@ -1,3 +1,5 @@
+# @summary Assert that the Bolt executable running PEAdm is a supported version
+#
 # Checks if the current Bolt version matches the SemVerRange defined in $supported_bolt_version
 # Fails the calling plan if false, does nothing if true.
 # Accepts a parameter for the $supported_bolt_version for unit testing purposes

functions/assert_supported_bolt_version.pp

@@ -1,3 +1,4 @@
+# @summary Assert that the PE version given is supported by PEAdm
 # @return [Boolean] true if the version is supported, raise error otherwise
 # @param [String] the version number to check
 function peadm::assert_supported_pe_version (

functions/assert_supported_pe_version.pp

@@ -1,3 +1,12 @@
+# @summary Return the certname of the given target-like input
+#
+# This function accepts a variety of data types which could represent single
+# targets, and returns the certname corresponding to the input.
+#
+# For Target objects, or arrays of a single Target object, a "certname" var can
+# be set, which determines that target's certname. Otherwise, the target's name
+# is its certname. For strings, the certname is equal to the string. Undef
+# input returns undef.
 function peadm::certname(
   Variant[Target,
           String,

functions/certname.pp

@@ -1,4 +1,5 @@
-# Used during the peadm::convert plan
+# @api private
+# @summary Used during the peadm::convert plan
 class peadm::setup::convert_node_manager {
   require peadm::setup::node_manager
 

manifests/setup/convert_node_manager.pp

@@ -1,3 +1,4 @@
+# @api private
 # @summary Defines configuration needed for converting PE 2018
 #
 class peadm::setup::convert_pre20197 {

manifests/setup/convert_pre20197.pp

@@ -1,4 +1,7 @@
-# This profile is not intended to be continously enforced on PE primaries.
+# @api private
+# @summary Configures PEAdm's required node groups
+#
+# This class is not intended to be continously enforced on PE primaries.
 # Rather, it describes state to enforce as a boostrap action, preparing the
 # Puppet Enterprise console with a sane default environment configuration.
 #

manifests/setup/node_manager.pp

@@ -1,5 +1,10 @@
-# Set up the node_manager.yaml file in the temporary Bolt confdir so that
-# node_group resources may be used during Bolt apply runs
+# @api private
+# @summary Set up the node_manager.yaml file in the temporary Bolt confdir
+#
+# This configuration permits node_group resources to be used during Bolt apply
+# runs. It is necessary to do it this way because node_manager requires a
+# configuration file, located in $confdir. But, when Bolt applies a catalog, it
+# does so using a unique, dynamic $confdir.
 class peadm::setup::node_manager_yaml (
   String $primary_host
 ) {

manifests/setup/node_manager_yaml.pp

@@ -1,3 +1,8 @@
+# @summary Convert an existing PE cluster to a PEAdm-managed cluster
+#
+# This plan sets required certificate extensions on PE nodes, and configures
+# the required PE node groups to make an existing cluster compatible with
+# management using PEAdm.
 plan peadm::convert (
   # Standard
   Peadm::SingleTargetSpec           $primary_host,