Merge pull request #8601 from hestonhoffman/more-docs-fixes

(Docs)(maint) Fix more strings formatting issues

Author: joshcooper

lib/puppet/defaults.rb

@@ -878,8 +878,8 @@ def self.initialize_default_settings!(settings)
 **Note:** The list of alternate names is locked in when the server's
 certificate is signed. If you need to change the list later, you can't just
 change this setting; you also need to regenerate the certificate. For more
-information on that process, see the [cert regen docs]
-(https://puppet.com/docs/puppet/latest/ssl_regenerate_certificates.html).
+information on that process, see the 
+[cert regen docs](https://puppet.com/docs/puppet/latest/ssl_regenerate_certificates.html).
 
 To see all the alternate names your servers are using, log into your CA server
 and run `puppetserver ca list --all`, then check the output for `(alt names: ...)`.

lib/puppet/functions/all.rb

@@ -51,7 +51,7 @@
 # notice $data.all |$key, $value| { $value % 10 == 0  and $key =~ /^abc/ }
 # ```
 #
-# Would notice true.
+# Would notice `true`.
 #
 # For an general examples that demonstrates iteration, see the Puppet
 # [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)

lib/puppet/functions/capitalize.rb

@@ -18,14 +18,14 @@
 # 'hello'.capitalize()
 # upcase('hello')
 # ```
-# Would both result in "Hello"
+# Would both result in `"Hello"`
 #
 # @example Capitalizing strings in an Array
 # ```puppet
 # ['abc', 'bcd'].capitalize()
 # capitalize(['abc', 'bcd'])
 # ```
-# Would both result in ['Abc', 'Bcd']
+# Would both result in `['Abc', 'Bcd']`
 #
 Puppet::Functions.create_function(:capitalize) do
 

lib/puppet/functions/downcase.rb

@@ -22,14 +22,14 @@
 # 'HELLO'.downcase()
 # downcase('HEllO')
 # ```
-# Would both result in "hello"
+# Would both result in `"hello"`
 #
 # @example Converting an Array to lower case
 # ```puppet
 # ['A', 'B'].downcase()
 # downcase(['A', 'B'])
 # ```
-# Would both result in ['a', 'b']
+# Would both result in `['a', 'b']`
 #
 # @example Converting a Hash to lower case
 # ```puppet

lib/puppet/functions/get.rb

@@ -23,20 +23,20 @@
 # #get($facts, 'os.family')
 # $facts.get('os.family')
 # ```
-# Would both result in the value of $facts['os']['family']
+# Would both result in the value of `$facts['os']['family']`
 #
 # @example Getting the value from an expression
 # ```puppet
 # get([1,2,[{'name' =>'waldo'}]], '2.0.name')
 # ```
-# Would result in 'waldo'
+# Would result in `'waldo'`
 #
 # @example Using a default value
 # ```puppet
 # get([1,2,[{'name' =>'waldo'}]], '2.1.name', 'not waldo')
 #
 # ```
-# Would result in 'not waldo'
+# Would result in `'not waldo'`
 #
 # @example Quoting a key with period
 # ```puppet
@@ -128,8 +128,8 @@ def get_from_value(value, navigation, default_value = nil, &block)
 
     # Note: split_key always processes the initial segment as a string even if it could be an integer.
     # This since it is designed for lookup keys. For a numeric first segment
-    # like '0.1' the wanted result is [0,1], not ["0", 1]. The workaround here is to
-    # prefix the navigation with "x." thus giving split_key a first segment that is a string.
+    # like '0.1' the wanted result is `[0,1]`, not `["0", 1]`. The workaround here is to
+    # prefix the navigation with `"x."` thus giving split_key a first segment that is a string.
     # The fake segment is then dropped.
     segments = split_key("x." + navigation) {|err| _("Syntax error in dotted-navigation string")}
     segments.shift

lib/puppet/functions/group_by.rb

@@ -4,14 +4,22 @@
 # and the values are arrays of elements in the collection that correspond to the key.
 Puppet::Functions.create_function(:group_by) do
   # @param collection A collection of things to group.
-  # @example Group array of strings by length, results in e.g. { 1 => [a, b], 2 => [ab] }
+  # @example Group array of strings by length, results in e.g. `{ 1 => [a, b], 2 => [ab] }`
+  #   ```puppet
   #   [a, b, ab].group_by |$s| { $s.length }
-  # @example Group array of strings by length and index, results in e.g. {1 => ['a'], 2 => ['b', 'ab']}
+  #   ```
+  # @example Group array of strings by length and index, results in e.g. `{1 => ['a'], 2 => ['b', 'ab']}`
+  #   ```puppet
   #   [a, b, ab].group_by |$i, $s| { $i%2 + $s.length }
-  # @example Group hash iterating by key-value pair, results in e.g. { 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }
+  #   ```
+  # @example Group hash iterating by key-value pair, results in e.g. `{ 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }`
+  #   ```puppet
   #   { a => [1, 2], b => [1] }.group_by |$kv| { $kv[1].length }
-  # @example Group hash iterating by key and value, results in e.g. { 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }
-  #   { a => [1, 2], b => [1] }.group_by |$k, $v| { $v.length }
+  #   ```
+  # @example Group hash iterating by key and value, results in e.g. `{ 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }`
+  #   ```puppet
+  #    { a => [1, 2], b => [1] }.group_by |$k, $v| { $v.length }
+  #   ```
   dispatch :group_by_1 do
     required_param 'Collection', :collection
     block_param 'Callable[1,1]', :block

lib/puppet/functions/lest.rb

@@ -23,7 +23,7 @@
 #  .lest || { fail("no value for $data[a][b][c]" }
 # ```
 #
-# Would fail the operation because $data[a][b][c] results in `undef`
+# Would fail the operation because `$data[a][b][c]` results in `undef`
 # (there is no `b` key in `a`).
 #
 # In contrast - this example: