From e8ea22d86eaf089e795300a31712cd6ad4d86bb9 Mon Sep 17 00:00:00 2001 From: Alexis Mousset Date: Fri, 5 Feb 2016 17:20:56 +0100 Subject: [PATCH] Fixes #7879: Add documentation for ncf generic methods --- tree/30_generic_methods/command_execution_result.cf | 9 +++++---- tree/30_generic_methods/directory_check_exists.cf | 7 ++++--- tree/30_generic_methods/file_check_exists.cf | 8 +++++--- tree/30_generic_methods/file_download.cf | 4 ++++ .../http_request_check_status_headers.cf | 3 ++- tree/30_generic_methods/http_request_content_headers.cf | 4 +++- tree/30_generic_methods/package_check_installed.cf | 7 ++++--- tree/30_generic_methods/package_install_version_cmp.cf | 9 +++++---- .../package_install_version_cmp_update.cf | 9 +++++---- tree/30_generic_methods/package_remove.cf | 9 ++++++--- tree/30_generic_methods/user_absent.cf | 1 + tree/30_generic_methods/user_create.cf | 3 +-- 12 files changed, 45 insertions(+), 28 deletions(-) diff --git a/tree/30_generic_methods/command_execution_result.cf b/tree/30_generic_methods/command_execution_result.cf index 8d4de40e9..3d90abecc 100644 --- a/tree/30_generic_methods/command_execution_result.cf +++ b/tree/30_generic_methods/command_execution_result.cf @@ -18,6 +18,10 @@ # @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) @@ -25,11 +29,8 @@ # # @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 index 800f2ed61..5cec4f44d 100644 --- a/tree/30_generic_methods/directory_check_exists.cf +++ b/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) { diff --git a/tree/30_generic_methods/file_check_exists.cf b/tree/30_generic_methods/file_check_exists.cf index 6ff6bdb24..046473dc5 100644 --- a/tree/30_generic_methods/file_check_exists.cf +++ b/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) { diff --git a/tree/30_generic_methods/file_download.cf b/tree/30_generic_methods/file_download.cf index 5b505b3bb..f9fb5c39c 100644 --- a/tree/30_generic_methods/file_download.cf +++ b/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 diff --git a/tree/30_generic_methods/http_request_check_status_headers.cf b/tree/30_generic_methods/http_request_check_status_headers.cf index de2040ec1..ab09c1d0d 100644 --- 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 diff --git a/tree/30_generic_methods/http_request_content_headers.cf b/tree/30_generic_methods/http_request_content_headers.cf index cb219653d..0542919ae 100644 --- 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 diff --git a/tree/30_generic_methods/package_check_installed.cf b/tree/30_generic_methods/package_check_installed.cf index 7f362a28d..fdd0c0610 100644 --- a/tree/30_generic_methods/package_check_installed.cf +++ b/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) { diff --git a/tree/30_generic_methods/package_install_version_cmp.cf b/tree/30_generic_methods/package_install_version_cmp.cf index 6c22bd5d1..27821aca8 100644 --- 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 ==,<=,>=,<,>,!= @@ -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) { diff --git a/tree/30_generic_methods/package_install_version_cmp_update.cf b/tree/30_generic_methods/package_install_version_cmp_update.cf index e59536eb8..3caf0f75b 100644 --- a/tree/30_generic_methods/package_install_version_cmp_update.cf +++ b/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) { diff --git a/tree/30_generic_methods/package_remove.cf b/tree/30_generic_methods/package_remove.cf index faf33dc65..7c8ee51ce 100644 --- a/tree/30_generic_methods/package_remove.cf +++ b/tree/30_generic_methods/package_remove.cf @@ -18,6 +18,11 @@ # @name Package remove # @description Remove a package +# @documentation *Example*: +# ``` +# methods: +# "any" usebundle => package_remove("htop"); +# ``` # # @parameter package_name Name of the package to remove # @@ -25,9 +30,7 @@ # @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) { diff --git a/tree/30_generic_methods/user_absent.cf b/tree/30_generic_methods/user_absent.cf index 2709833c2..9c3ec5e61 100644 --- a/tree/30_generic_methods/user_absent.cf +++ b/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 diff --git a/tree/30_generic_methods/user_create.cf b/tree/30_generic_methods/user_create.cf index 270927a04..57356d534 100644 --- a/tree/30_generic_methods/user_create.cf +++ b/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)