Fixes #7879: Add documentation for ncf generic methods

tree/30_generic_methods/command_execution_result.cf

@@ -18,18 +18,19 @@
 
 # @name Command execution result
 # @description Execute a command and create outcome classes depending on its exit code
+# @documentation Execute a command and create outcome classes
+# depending on the exit codes given in parameters.
+# If an exit code is not in the list it will lead to an error status. 
+# If you want 0 to be a success you have to list it in the kept_codes list
 #
 # @parameter command        The command to run
 # @parameter kept_codes     List of codes that produce a kept status separated with commas (ex: 1,2,5)
 # @parameter repaired_codes List of codes that produce a repaired status separated with commas (ex: 3,4,6)
 # 
 # @class_prefix command_execution_result
 # @class_parameter command
-# 
 # This bundle will define a class command_execution_result_${command}_{kept,repaired,not_ok,ok,reached}
-# depending on the exit codes given in parameters.
-# If an exit code is not in the list it will lead to an error status.
-# If you want 0 to be a success you have to list it in the kept_codes list
+
 
 bundle agent command_execution_result(command, kept_codes, repaired_codes)
 {

tree/30_generic_methods/directory_check_exists.cf

@@ -18,14 +18,15 @@
 
 # @name Directory check exists
 # @description Checks if a directory exists
+# @documentation This bundle will define a class directory_check_exists_${directory_name}_{ok, reached, kept} if the
+# directory exists, or directory_check_exists_${directory_name}_{not_ok, reached, not_kept, failed} if
+# the directory doesn't exists
 #
 # @parameter directory_name Full path of the directory to check
 # 
 # @class_prefix directory_check_exists
 # @class_parameter directory_name
-# This bundle will define a class directory_check_exists_${directory_name}_{ok, reached, kept} if the
-# directory exists, or directory_check_exists_${directory_name}_{not_ok, reached, not_kept, failed} if
-# the directory doesn't exists
+# This bundle will define a class directory_check_exists_${directory_name}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent directory_check_exists(directory_name)
 {

tree/30_generic_methods/file_check_exists.cf

@@ -18,14 +18,16 @@
 
 # @name File check exists
 # @description Checks if a file exists
+# @documentation This bundle will define a class file_check_exists_${file_name}_{ok, reached, kept} if the
+# file exists, or file_check_exists_${file_name}_{not_ok, reached, not_kept, failed} if
+# the file doesn't exists
 #
 # @parameter file_name File name
 # 
 # @class_prefix file_check_exists
 # @class_parameter file_name
-# This bundle will define a class file_check_exists_${file_name}_{ok, reached, kept} if the
-# file exists, or file_check_exists_${file_name}_{not_ok, reached, not_kept, failed} if
-# the file doesn't exists
+# This bundle will define a class file_check_exists_${file_name}_{kept,repaired,not_ok,ok,reached}
+
 
 bundle agent file_check_exists(file_name)
 {

tree/30_generic_methods/file_download.cf

@@ -18,6 +18,10 @@
 
 # @name File download
 # @description Download a file if it does not exit, using curl with a fallback on wget
+# @documentation This method finds a HTTP command-line tool and downloads the given source
+# into the destination.
+# 
+# It tries `curl` first, and `wget` as fallback.
 #
 # @parameter source      URL to download from
 # @parameter destination File destination

tree/30_generic_methods/http_request_check_status_headers.cf

@@ -17,7 +17,8 @@
 #####################################################################################
 
 # @name HTTP request check status with headers
-# @description Perform a HTTP request on the URL, method and headers provided and check that the response has the expected status code (ie 200, 404, 503, etc)
+# @description Checks status of an HTTP URL
+# @documentation Perform a HTTP request on the URL, method and headers provided and check that the response has the expected status code (ie 200, 404, 503, etc)
 #
 # @parameter method Method to call the URL (GET, POST, PUT, DELETE)
 # @parameter url URL to query

tree/30_generic_methods/http_request_content_headers.cf

@@ -17,7 +17,9 @@
 #####################################################################################
 
 # @name HTTP request sending content with headers
-# @description Perform a HTTP request on the URL, method and headers provided and send the content provided. Will return an error if the request failed.
+# @description Make an HTTP request with a specific header
+# @documentation Perform a HTTP request on the URL, method and headers provided 
+# and send the content provided. Will return an error if the request failed.
 #
 # @parameter method Method to call the URL (POST, PUT)
 # @parameter url URL to send content to

tree/30_generic_methods/package_check_installed.cf

@@ -18,15 +18,16 @@
 
 # @name Package check installed
 # @description Verify if a package is installed in any version
+# @documentation # This bundle will define a class package_check_installed_${file_name}_{ok, reached, kept} if the
+# package is installed, or package_check_installed_${file_name}_{not_ok, reached, not_kept, failed} if
+# the package is not installed
 #
 # @parameter package_name Name of the package to check
 #
 # @class_prefix package_check_installed
 # @class_parameter package_name
 
-# This bundle will define a class package_check_installed_${file_name}_{ok, reached, kept} if the
-# package is installed, or package_check_installed_${file_name}_{not_ok, reached, not_kept, failed} if
-# the package is not installed
+# This bundle will define a class package_check_installed_${file_name}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent package_check_installed(package_name)
 {

tree/30_generic_methods/package_install_version_cmp.cf

@@ -18,6 +18,11 @@
 
 # @name Package install version compare
 # @description Install a package or verify if it is installed in a specific version, or higher or lower version than a version specified
+# @documentation *Example*:
+# ```
+# methods:
+#     "any" usebundle => package_install_version_cmp("postgresql", ">=", "9.1", "verify");
+# ```
 #
 # @parameter package_name        Name of the package to install or verify
 # @parameter version_comparator  Comparator between installed version and defined version, can be ==,<=,>=,<,>,!=
@@ -27,10 +32,6 @@
 # @class_prefix package_install
 # @class_parameter package_name
 # This bundle will define a class package_install_${package_name}_{kept,repaired,not_ok,ok,reached}
-# 
-# Usage example:
-# methods:
-#     "any" usebundle => package_install_version_cmp("postgresql", ">=", "9.1", "verify");
 
 bundle agent package_install_version_cmp(package_name, version_comparator, package_version, action)
 {

tree/30_generic_methods/package_install_version_cmp_update.cf

@@ -18,6 +18,11 @@
 
 # @name Package install version compare (update optional)
 # @description Install a package or verify if it is installed in a specific version, or higher or lower version than a version specified, optionally test update or not (Debian-, Red Hat- or SuSE-like systems only)
+# @documentation *Example*:
+# ```
+# methods:
+#     "any" usebundle => package_install_version_cmp_update("postgresql", ">=", "9.1", "verify", "false");
+# ```
 #
 # @parameter package_name        Name of the package to install or verify
 # @parameter version_comparator  Comparator between installed version and defined version, can be ==,<=,>=,<,>,!=
@@ -28,10 +33,6 @@
 # @class_prefix package_install
 # @class_parameter package_name
 # This bundle will define a class package_install_${package_name}_{kept,repaired,not_ok,ok,reached}
-# 
-# Usage example:
-# methods:
-#     "any" usebundle => package_install_version_cmp_update("postgresql", ">=", "9.1", "verify", "false");
 
 bundle agent package_install_version_cmp_update(package_name, version_comparator, package_version, action, update_policy)
 {

tree/30_generic_methods/package_remove.cf

@@ -18,16 +18,19 @@
 
 # @name Package remove
 # @description Remove a package
+# @documentation *Example*:
+# ```
+# methods:
+#     "any" usebundle => package_remove("htop");
+# ```
 #
 # @parameter package_name        Name of the package to remove
 #
 # @class_prefix package_remove
 # @class_parameter package_name
 # This bundle will define a class package_remove_${package_name}_{kept,repaired,not_ok,ok,reached}
 #
-# Usage example:
-# methods:
-#     "any" usebundle => package_remove("htop");
+
 
 bundle agent package_remove(package_name)
 {

tree/30_generic_methods/user_absent.cf

@@ -18,6 +18,7 @@
 
 # @name User absent
 # @description Remove a user
+# @documentation This method ensures that a user does not exist on the system.
 # @agent_version >=3.6
 #
 # @parameter login User login

tree/30_generic_methods/user_create.cf

@@ -18,6 +18,7 @@
 
 # @name User create
 # @description Create a user
+# @documentation This method does not create the user's home directory.
 # @agent_version >=3.6
 #
 # @parameter login       User login
@@ -29,8 +30,6 @@
 # 
 # @class_prefix user_create
 # @class_parameter login
-# This method doesn't create the user's home directory. For a more comprehensive method,
-# see other user_* generic methods.
 # This bundle will define a class user_create_${login}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent user_create(login, description, home, group, shell, locked)