Merge pull request #328 from amousset/ust_7879/add_documentation_for_…

…ncf_generic_methods Fixes #7879: Add documentation for ncf generic methods
Normation · Mar 14, 2016 · ba2887e · ba2887e
2 parents 652c4f8 + 6087ada
commit ba2887e
Show file tree

Hide file tree

Showing 65 changed files with 61 additions and 112 deletions.
diff --git a/tree/30_generic_methods/command_execution.cf b/tree/30_generic_methods/command_execution.cf
@@ -23,7 +23,6 @@
 # 
 # @class_prefix command_execution
 # @class_parameter command_name
-# This bundle will define a class command_execution_${command_name}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent command_execution(command_name)
 {

diff --git a/tree/30_generic_methods/command_execution_result.cf b/tree/30_generic_methods/command_execution_result.cf
@@ -18,18 +18,17 @@
 
 # @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)
 {

diff --git a/tree/30_generic_methods/directory_check_exists.cf b/tree/30_generic_methods/directory_check_exists.cf
@@ -18,14 +18,14 @@
 
 # @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
 
 bundle agent directory_check_exists(directory_name)
 {

diff --git a/tree/30_generic_methods/directory_create.cf b/tree/30_generic_methods/directory_create.cf
@@ -23,7 +23,6 @@
 #
 # @class_prefix directory_create
 # @class_parameter target
-# This bundle will define a class directory_create_${target}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent directory_create(target)
 {

diff --git a/tree/30_generic_methods/file_check_exists.cf b/tree/30_generic_methods/file_check_exists.cf
@@ -18,14 +18,14 @@
 
 # @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
 
 bundle agent file_check_exists(file_name)
 {

diff --git a/tree/30_generic_methods/file_copy_from_local_source.cf b/tree/30_generic_methods/file_copy_from_local_source.cf
@@ -24,7 +24,6 @@
 # 
 # @class_prefix file_copy_from_local_source
 # @class_parameter destination
-# This bundle will define a class file_copy_from_local_source_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_copy_from_local_source(source, destination)
 {

diff --git a/tree/30_generic_methods/file_copy_from_local_source_recursion.cf b/tree/30_generic_methods/file_copy_from_local_source_recursion.cf
@@ -25,7 +25,6 @@
 # 
 # @class_prefix file_copy_from_local_source
 # @class_parameter destination
-# This bundle will define a class file_copy_from_local_source_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_copy_from_local_source_recursion(source, destination, recursion)
 {

diff --git a/tree/30_generic_methods/file_copy_from_remote_source.cf b/tree/30_generic_methods/file_copy_from_remote_source.cf
@@ -41,7 +41,6 @@
 # 
 # @class_prefix file_copy_from_remote_source
 # @class_parameter destination
-# This bundle will define a class file_copy_from_remote_source_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_copy_from_remote_source(source, destination)
 {

diff --git a/tree/30_generic_methods/file_copy_from_remote_source_recursion.cf b/tree/30_generic_methods/file_copy_from_remote_source_recursion.cf
@@ -37,7 +37,6 @@
 # 
 # @class_prefix file_copy_from_remote_source
 # @class_parameter destination
-# This bundle will define a class file_copy_from_remote_source_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_copy_from_remote_source_recursion(source, destination, recursion)
 {

diff --git a/tree/30_generic_methods/file_create.cf b/tree/30_generic_methods/file_create.cf
@@ -23,7 +23,6 @@
 #
 # @class_prefix file_create
 # @class_parameter target
-# This bundle will define a class file_create_${target}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_create(target)
 {

diff --git a/tree/30_generic_methods/file_create_symlink.cf b/tree/30_generic_methods/file_create_symlink.cf
@@ -24,7 +24,6 @@
 # 
 # @class_prefix file_create_symlink
 # @class_parameter destination
-# This bundle will define a class file_create_symlink_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_create_symlink(source, destination)
 {

diff --git a/tree/30_generic_methods/file_create_symlink_enforce.cf b/tree/30_generic_methods/file_create_symlink_enforce.cf
@@ -25,7 +25,6 @@
 # 
 # @class_prefix file_create_symlink
 # @class_parameter destination
-# This bundle will define a class file_create_symlink_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_create_symlink_enforce(source, destination, enforce)
 {

diff --git a/tree/30_generic_methods/file_create_symlink_force.cf b/tree/30_generic_methods/file_create_symlink_force.cf
@@ -24,7 +24,6 @@
 # 
 # @class_prefix file_create_symlink
 # @class_parameter destination
-# This bundle will define a class file_create_symlink_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_create_symlink_force(source, destination)
 {

diff --git a/tree/30_generic_methods/file_download.cf b/tree/30_generic_methods/file_download.cf
@@ -18,13 +18,16 @@
 
 # @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
 # 
 # @class_prefix file_download
 # @class_parameter destination
-# This bundle will define a class file_download_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_download(source, destination)
 {

diff --git a/tree/30_generic_methods/file_enforce_content.cf b/tree/30_generic_methods/file_enforce_content.cf
@@ -25,7 +25,6 @@
 # 
 # @class_prefix file_ensure_lines_present
 # @class_parameter file
-# This bundle will define a class file_ensure_lines_present_${file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_enforce_content(file, lines, enforce)
 {

diff --git a/tree/30_generic_methods/file_ensure_block_in_section.cf b/tree/30_generic_methods/file_ensure_block_in_section.cf
@@ -26,8 +26,7 @@
 #
 # @class_prefix file_ensure_block_in_section
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_block_in_section_${file}_{kept,repaired,not_ok,ok,reached}
+
 bundle agent file_ensure_block_in_section(file, section_start, section_end, block)
 {
   vars:

diff --git a/tree/30_generic_methods/file_ensure_block_present.cf b/tree/30_generic_methods/file_ensure_block_present.cf
@@ -24,8 +24,7 @@
 #
 # @class_prefix file_ensure_block_present
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_block_present_${file}_{kept,repaired,not_ok,ok,reached}
+
 bundle agent file_ensure_block_present(file, block)
 {
   vars:

diff --git a/tree/30_generic_methods/file_ensure_key_value_present_in_ini_section.cf b/tree/30_generic_methods/file_ensure_key_value_present_in_ini_section.cf
@@ -26,8 +26,6 @@
 #
 # @class_prefix file_ensure_key_value_present_in_ini_section
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_key_value_present_in_ini_section_${file}_{kept,repaired,not_ok,ok,not_ok,reached}
 
 bundle agent file_ensure_key_value_present_in_ini_section(file, section, name, value)
 {

diff --git a/tree/30_generic_methods/file_ensure_keys_values.cf b/tree/30_generic_methods/file_ensure_keys_values.cf
@@ -25,8 +25,6 @@
 #
 # @class_prefix file_ensure_keys_values
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_keys_values_${file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_ensure_keys_values(file, keys, separator)
 {

diff --git a/tree/30_generic_methods/file_ensure_line_present_in_ini_section.cf b/tree/30_generic_methods/file_ensure_line_present_in_ini_section.cf
@@ -25,8 +25,6 @@
 #
 # @class_prefix file_ensure_line_present_in_ini_section
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_line_present_in_ini_section_${file}_{kept,repaired,not_ok,ok,not_ok,reached}
 
 bundle agent file_ensure_line_present_in_ini_section(file, section, line)
 {

diff --git a/tree/30_generic_methods/file_ensure_line_present_in_xml_tag.cf b/tree/30_generic_methods/file_ensure_line_present_in_xml_tag.cf
@@ -25,8 +25,6 @@
 #
 # @class_prefix file_ensure_line_present_in_xml_tag
 # @class_parameter file
-#
-# This bundle will define a class file_ensure_line_present_in_xml_tag_${file}_{kept,repaired,failed,ok,not_ok,reached}
 
 bundle agent file_ensure_line_present_in_xml_tag(file, tag, line)
 {

diff --git a/tree/30_generic_methods/file_ensure_lines_absent.cf b/tree/30_generic_methods/file_ensure_lines_absent.cf
@@ -24,7 +24,6 @@
 #
 # @class_prefix file_ensure_lines_absent
 # @class_parameter file
-# This bundle will define a class file_ensure_lines_absent_${file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_ensure_lines_absent(file, lines)
 {

diff --git a/tree/30_generic_methods/file_ensure_lines_present.cf b/tree/30_generic_methods/file_ensure_lines_present.cf
@@ -24,7 +24,6 @@
 # 
 # @class_prefix file_ensure_lines_present
 # @class_parameter file
-# This bundle will define a class file_ensure_lines_present_${file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_ensure_lines_present(file, lines)
 {

diff --git a/tree/30_generic_methods/file_from_template.cf b/tree/30_generic_methods/file_from_template.cf
@@ -24,7 +24,6 @@
 #
 # @class_prefix file_from_template
 # @class_parameter destination
-# This bundle will define a class file_from_template_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_from_template(source_template, destination)
 {

diff --git a/tree/30_generic_methods/file_from_template_mustache.cf b/tree/30_generic_methods/file_from_template_mustache.cf
@@ -25,7 +25,6 @@
 #
 # @class_prefix file_from_template
 # @class_parameter destination
-# This bundle will define a class file_from_template_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_from_template_mustache(source_template, destination)
 {

diff --git a/tree/30_generic_methods/file_from_template_type.cf b/tree/30_generic_methods/file_from_template_type.cf
@@ -26,7 +26,6 @@
 #
 # @class_prefix file_from_template
 # @class_parameter destination
-# This bundle will define a class file_from_template_${destination}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_from_template_type(source_template, destination, template_type)
 {

diff --git a/tree/30_generic_methods/file_remove.cf b/tree/30_generic_methods/file_remove.cf
@@ -23,7 +23,6 @@
 #
 # @class_prefix file_remove
 # @class_parameter target
-# This bundle will define a class file_remove_${target}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_remove(target)
 {

diff --git a/tree/30_generic_methods/file_replace_lines.cf b/tree/30_generic_methods/file_replace_lines.cf
@@ -25,8 +25,6 @@
 #
 # @class_prefix file_replace_lines
 # @class_parameter file
-#
-# This bundle will define a class file_replace_lines_${file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_replace_lines(file, line, replacement)
 {

diff --git a/tree/30_generic_methods/file_template_expand.cf b/tree/30_generic_methods/file_template_expand.cf
@@ -27,8 +27,6 @@
 #
 # @class_prefix file_template_expand
 # @class_parameter target_file
-#
-# This bundle will define a class file_template_expand_${target_file}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent file_template_expand(tml_file, target_file, mode, owner, group)
 {

diff --git a/tree/30_generic_methods/group_absent.cf b/tree/30_generic_methods/group_absent.cf
@@ -24,7 +24,6 @@
 
 # @class_prefix group_absent
 # @class_parameter group
-# This bundle will define a class group_absent_${group}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent group_absent(group)
 {

diff --git a/tree/30_generic_methods/group_present.cf b/tree/30_generic_methods/group_present.cf
@@ -24,7 +24,6 @@
 
 # @class_prefix group_present
 # @class_parameter group
-# This bundle will define a class group_present_${group}_{kept,repaired,not_ok,ok,reached}
 
 bundle agent group_present(group)
 {

diff --git a/tree/30_generic_methods/http_request_check_status_headers.cf b/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
@@ -26,7 +27,6 @@
 
 # @class_prefix http_request_check_status_headers
 # @class_parameter url
-# This bundle will define a class http_request_check_status_headers_${url}_{kept,not_ok,ok,reached}
 
 bundle agent http_request_check_status_headers(method, url, expected_status, headers)
 {

diff --git a/tree/30_generic_methods/http_request_content_headers.cf b/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
@@ -26,7 +28,6 @@
 
 # @class_prefix http_content_headers
 # @class_parameter url
-# This bundle will define a class http_content_headers_${url}_{repaired,not_ok,ok,reached}
 
 bundle agent http_request_content_headers(method, url, content, headers)
 {

diff --git a/tree/30_generic_methods/package_check_installed.cf b/tree/30_generic_methods/package_check_installed.cf
@@ -18,16 +18,15 @@
 
 # @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
-
 bundle agent package_check_installed(package_name)
 {
   vars:

diff --git a/tree/30_generic_methods/package_install.cf b/tree/30_generic_methods/package_install.cf
@@ -23,7 +23,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}
 
 bundle agent package_install(package_name)
 {

diff --git a/tree/30_generic_methods/package_install_version.cf b/tree/30_generic_methods/package_install_version.cf
@@ -24,7 +24,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}
 
 bundle agent package_install_version(package_name, package_version)
 {

diff --git a/tree/30_generic_methods/package_install_version_cmp.cf b/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 ==,<=,>=,<,>,!=
@@ -26,11 +31,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)
 {