Fixes #17464: Improve Augeas generic methods documentation

tree/30_generic_methods/file_augeas_commands.cf

@@ -17,13 +17,41 @@
 #####################################################################################
 #
 # @name File Augeas commands
-# @description Use augeas binaries to execute augtool command(s) directly on the agent. 
-# The generic method will return the command(s) execution output otherwise if the augeas isn't installed on the agent, it will produces an error.
+# @description Use Augeas binaries to execute augtool commands and options directly on the agent. 
 #
+# @documentation Augeas is a tool that provides an abstraction layer for all the complexities that turn around editing files with regular expressions.
+# It's a tree based hierarchy tool, that handles system configuration files where you can securely modify your files and to do so you have to provide 
+# the path to the node label's value.
+# Augeas uses lenses which are like sort of modules that are in charge of identifying and converting files into tree and back. 
+# This way, you can manipulate at first the tree and then save changes into the configuration files on the system.
+#
+# This method gives the possibilty to enter a list of augtool commands and options as a parameter. The method has in total 4 parameters: variable_prefix, variable_name, commands and autoload.
+# Augtool provides bunch of other commands and options that you can use in this generic method such as 'match' to print the matches for a specific 
+# path expression, 'span' to print position in input file corresponding to tree, 'retrieve' to transform tree into text and 'save' to save all pending changes.
+# If Augeas isn't installed on the agent, it will produces an error.
+#
+# The particular thing you may want to do with this method is using it depending on you needs and in two cases.
+#
+# # Use case 1: 
+# The first case includes activating the `autoload` option, it is `true` by default, means you can leave the `autoload` parameter's field empty and Augeas will 
+# accordingly charge all files and lenses before executing the commands you have specified. Below is an example that will shows as a result the configuration 
+# files that are parsed by default in `/files/etc` directory and then also print the content of the `sshd_config` file, you can either leave the `autoload`
+# parameter empty or fill it by putting `true` as a value.
+# ```
+# file_augeas_commands("label","value","ls /files/etc \n print /files/etc/ssh/sshd_config","")
+# file_augeas_commands("label","value","ls /files/etc \n print /files/etc/ssh/sshd_config","true")
+# ```
+# # Use case 2: 
+# The second case is when you deactivate that option which means that you are specifying `false` as parameter and in this case you have to 
+# charge manually your files and lenses in the commands parameter by using the set commands. Below is the second example where you can for example set 
+# the lens and the file then verifying by checking the `/augeas/load` path.
+# ```
+# file_augeas_commands("label","value","set /augeas/load/Sshd/lens "Sshd.lns \n set /augeas/load/Sshd/incl "/etc/ssh/sshd_config" \n load \n print /augeas/load/Sshd \n print /augeas/load/Sshd \n print /files/etc/ssh/sshd_config","false")
+# ```
 # @parameter variable_prefix The prefix of the variable name
 # @parameter variable_name   The variable to define, the full name will be variable_prefix.variable_name
 # @parameter commands        The augeas command(s) 
-# @parameter autoload        Deactivate the '--autoload' option if you don't want augeas to charge all the files/lens, it's 'true' by default.
+# @parameter autoload        Deactivate the `autoload` option if you don't want augeas to charge all the files/lens, it's `true` by default.
 # @parameter_constraint autoload "allow_empty_string" : true
 # @parameter_constraint autoload "select" : [ "", "true", "false" ]
 # @class_prefix file_augeas_commands

tree/30_generic_methods/file_augeas_set.cf

@@ -17,18 +17,40 @@
 #####################################################################################
 #
 # @name File Augeas set 
-# @description Use Augeas binaries to call Augtool command and set a node's label value.
-# @documentation There is two ways you can use this method, either you simply provide a path to the node label as a parameter or you can specify a file associated with a lens then the regular path. When you only specify the path to the node label's, your request will include by default Augeas charging all the lenses and files, on the other hand, if you have a specific file for example such as a json file and you want to associate it to the existing Json lense, then in that case you need to specify in addition the file and lens parameter, this way Augeas won't load all its files and lenses except the ones you specified. 
-# The generic method will set a node's label value otherwise if Augeas isn't installed on the agent, it will produces an error. 
-# The method provides a way to make a backup of the file before applying any changes on it, you can find them under '/var/rudder/modified-files/'.
+# @description Use Augeas binaries to call Augtool commands and options to set a node label's value.
+#
+# @documentation Augeas is a tool that provides an abstraction layer for all the complexities that turn around editing files with regular expressions.
+# It's a tree based hierarchy tool, that handles system configuration files where you can securely modify your files and to do so you have to provide 
+# the path to the node label's value.
+# Augeas uses lenses which are like sort of modules that are in charge of identifying and converting files into tree and back. 
+# This way, you can manipulate at first the tree and then save changes into the configuration files on the system.
+# 
+# In this method, we introduce using augtool commands and options in order to set the value of a given node's label in the parameters 
+# (which means that you simply want to modify your configuration file), this can be done by specifying the path to it. 
+# The method has in total 4 parameters: path, value, lens and hosts.
+#
+# Actually there is two ways you can use this method, either you simply provide a path to the node's label as a parameter or you specify a file 
+# associated with a lens then you put the regular path. When you only specify the path to the node's label, your request will includes by default Augeas 
+# charging all the lenses and files, on the other hand, if you have a specific file for example such as a Json file and you want to associate it 
+# to the existing Json lense, then in that case, you need to fill in addition the file and the lens parameter, this way Augeas won't load all its files and 
+# lenses except the ones you have specified. 
+#
+# The generic method will set a node label's value on the agent, otherwise, if Augeas isn't installed on the agent, it will produces an error. 
+# The method provides a way to make a backup of the file you modified before applying any changes on the node, you can find them in the '/var/rudder/modified-files/' directory.
 #
 # #### Two uses cases examples:
 # 
-# # Use case 1: To simply set the value of the ip address of the first line in the '/etc/hosts' file to '192.168.1.5'
+# # Use case 1: In the first case, let's suppose that you want to simply set the value of the ip address of the first line in the `/etc/hosts` file to `192.168.1.5`, 
+# to do so you need to provide the path and value parameters.
+# ```
 # file_augeas_set("/etc/hosts/1/ipaddr","192.168.1.5");
-# # Use case 2: To associate the 'Hosts' lens with the '/etc/hosts' file then set the node value
+# ```
+#
+# # Use case 2: The second case includes two needs of using it, either you want to prevent Augeas from charging all lenses and files while executing your request or 
+# you want to associate the `Hosts` lens with the `/etc/hosts` file then set the value for the given path node.
 # file_augeas_set("/etc/hosts/1/ipaddr","192.168.1.5","Hosts","/etc/hosts");
 #
+#
 # @parameter path            The path to the file and node label
 # @parameter value           The value to set
 # @parameter lens            The lens specified by the user in case he wants to load a specified lens associated with its file

tree/30_generic_methods/variable_string_from_augeas.cf

@@ -17,16 +17,40 @@
 #####################################################################################
 #
 # @name Variable string from Augeas 
-# @description Use Augeas binaries to call Augtool command and get a node's label value.
-# @documentation There is two ways you can use this method, either you simply provide a path to the node label as a parameter or you can specify a file associated with a lens then the regular path. When you only specify the path to the node label's, your request will include by default Augeas charging all the lenses and files, on the other hand, if you have a specific file for example such as a json file and you want to associate it to the existing Json lense, then in that case you need to specify in addition the file and lens parameter, this way Augeas won't load all its files and lenses except the ones you specified. 
-# The generic method will get a node's label value otherwise if Augeas isn't installed on the agent, it will produces an error.
+# @description Use Augeas binaries to call Augtool commands and options to get a node label's value.
 #
+# @documentation Augeas is a tool that provides an abstraction layer for all the complexities that turn around editing files with regular expressions.
+# It's a tree based hierarchy tool, that handle system configuration files where you can securely modify your files. To do so you have to provide 
+# the path to the node label's value.
+# Augeas uses lenses which are sort of modules that are in charge of identifying and converting files into tree and back. 
+# This way, you can manipulate at first the tree and then save your changes into the configuration files on the actual system.
+#
+# In this method, we introduce using augtool commands and options in order to get the value of a given node's label in the parameters, this can be done 
+# by specifying the path to it. The method has in total 5 parameters: variable prefix, variable name, path, lens and file.
+#
+# Actually there is two ways you can use this method, either you simply provide a path to the node's label as a parameter or you specify a file 
+# associated with a lens, then you put the regular path. When you only specify the path to the node's label, your request will includes by default 
+# Augeas charging all the lenses and files, on the other hand, if you have a specific file, for example, such as a Json file and you want to associate it 
+# to the existing Json lense, then in that case, you need to fill in addition the file and the lens parameter, this way Augeas won't load all its files 
+# and lenses except the ones you have specified.
+# The generic method will get a node label's value from the agent, otherwise, if Augeas isn't installed on the agent, it will produces an error.
+# 
 # #### Two uses cases examples:
 # 
-# # Use case 1: To simply get the value of the ip address of the first line in the '/etc/hosts' file ('label' and 'value' are naming examples of 'variable_prefix' and 'variable_name')
+# # Use case 1: 
+# Let's consider that you want to obtain the value of the ip address of the first line in the `/etc/hosts` file by indicating the path to it.
+# (Note that the `label` and `value` parameters mentioned are naming examples of `variable prefix` and `variable name`, the path `/etc/hosts/1/ipaddr` 
+# represents the `ipaddr` node label's value in the first line in the `/etc/hosts`) .
+# ```
 # variable_string_from_augeas("label","value","/etc/hosts/1/ipaddr");
-# # Use case 2: To associate the 'Hosts' lens with the '/etc/hosts' file then get the node value
+# ```
+#
+# # Use case 2: 
+# The second case includes two needs of using it, either you want to prevent Augeas from charging all lenses and files while executing your request or 
+# you want to associate the `Hosts` lens with the `/etc/hosts` file then get for example the same node value of the first use case.
+# ```
 # variable_string_from_augeas("label","value","/etc/hosts/1/ipaddr","Hosts","/etc/hosts");
+# ```
 #
 # @parameter variable_prefix The prefix of the variable name
 # @parameter variable_name   The variable to define, the full name will be variable_prefix.variable_name