Misc fixes in the helpers to clean the autodoc

data/helpers.d/backend

@@ -2,7 +2,7 @@
 #
 # usage: ynh_use_logrotate [logfile] [--non-append]
 # | arg: logfile - absolute path of logfile
-# | option: --non-append - Replace the config file instead of appending this new config.
+# | arg: --non-append - (Option) Replace the config file instead of appending this new config.
 #
 # If no argument provided, a standard directory will be use. /var/log/${app}
 # You can provide a path with the directory only or with the logfile.
@@ -64,9 +64,9 @@ ynh_remove_logrotate () {
 
 # Create a dedicated systemd config
 #
-# usage: ynh_add_systemd_config [Service name] [Template name]
+# usage: ynh_add_systemd_config [service] [template]
-# | arg: Service name (optionnal, $app by default)
+# | arg: service - Service name (optionnal, $app by default)
-# | arg: Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template)
+# | arg: template - Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template)
 #
 # This will use the template ../conf/<templatename>.service
 # to generate a systemd config, by replacing the following keywords
@@ -76,7 +76,6 @@ ynh_remove_logrotate () {
 #   __APP__       by  $app
 #   __FINALPATH__ by  $final_path
 #
-# usage: ynh_add_systemd_config
 ynh_add_systemd_config () {
 	local service_name="${1:-$app}"
 
@@ -101,10 +100,9 @@ ynh_add_systemd_config () {
 
 # Remove the dedicated systemd config
 #
-# usage: ynh_remove_systemd_config [Service name]
+# usage: ynh_remove_systemd_config [service]
-# | arg: Service name (optionnal, $app by default)
+# | arg: service - Service name (optionnal, $app by default)
 #
-# usage: ynh_remove_systemd_config
 ynh_remove_systemd_config () {
 	local service_name="${1:-$app}"
 
@@ -119,6 +117,8 @@ ynh_remove_systemd_config () {
 
 # Create a dedicated nginx config
 #
+# usage: ynh_add_nginx_config
+#
 # This will use a template in ../conf/nginx.conf
 #   __PATH__      by  $path_url
 #   __DOMAIN__    by  $domain
@@ -126,7 +126,6 @@ ynh_remove_systemd_config () {
 #   __NAME__      by  $app
 #   __FINALPATH__ by  $final_path
 #
-# usage: ynh_add_nginx_config
 ynh_add_nginx_config () {
 	finalnginxconf="/etc/nginx/conf.d/$domain.d/$app.conf"
 	ynh_backup_if_checksum_is_different "$finalnginxconf"

data/helpers.d/ip

@@ -1,10 +1,10 @@
 # Validate an IP address
 #
+# usage: ynh_validate_ip [family] [ip_address]
+# | ret: 0 for valid ip addresses, 1 otherwise
+#
 # example: ynh_validate_ip 4 111.222.333.444
 #
-# usage: ynh_validate_ip <family> <ip_address>
-#
-# exit code : 0 for valid ip addresses, 1 otherwise
 ynh_validate_ip()
 {
   # http://stackoverflow.com/questions/319279/how-to-validate-ip-address-in-python#319298
@@ -31,8 +31,8 @@ EOF
 # example: ynh_validate_ip4 111.222.333.444
 #
 # usage: ynh_validate_ip4 <ip_address>
+# | ret: 0 for valid ipv4 addresses, 1 otherwise
 #
-# exit code : 0 for valid ipv4 addresses, 1 otherwise
 ynh_validate_ip4()
 {
   ynh_validate_ip 4 $1
@@ -44,8 +44,8 @@ ynh_validate_ip4()
 # example: ynh_validate_ip6 2000:dead:beef::1
 #
 # usage: ynh_validate_ip6 <ip_address>
+# | ret: 0 for valid ipv6 addresses, 1 otherwise
 #
-# exit code : 0 for valid ipv6 addresses, 1 otherwise
 ynh_validate_ip6()
 {
   ynh_validate_ip 6 $1

data/helpers.d/mysql

@@ -90,7 +90,7 @@ ynh_mysql_create_user() {
 #
 # usage: ynh_mysql_user_exists user
 # | arg: user - the user for which to check existence
-function ynh_mysql_user_exists()
+ynh_mysql_user_exists()
 {
    local user=$1
    if [[ -z $(ynh_mysql_execute_as_root "SELECT User from mysql.user WHERE User = '$user';") ]]
@@ -153,7 +153,7 @@ ynh_mysql_remove_db () {
 # Sanitize a string intended to be the name of a database
 # (More specifically : replace - and . by _)
 #
-# Exemple: dbname=$(ynh_sanitize_dbid $app)
+# example: dbname=$(ynh_sanitize_dbid $app)
 #
 # usage: ynh_sanitize_dbid name
 # | arg: name - name to correct/sanitize

data/helpers.d/system

@@ -1,18 +1,17 @@
 # Manage a fail of the script
 #
-# Print a warning to inform that the script was failed
+# usage: 
-# Execute the ynh_clean_setup function if used in the app script
+# ynh_exit_properly is used only by the helper ynh_abort_if_errors.
-#
+# You should not use it directly.
-# usage of ynh_clean_setup function
+# Instead, add to your script:
-# This function provide a way to clean some residual of installation that not managed by remove script.
-# To use it, simply add in your script:
 # ynh_clean_setup () {
 #        instructions...
 # }
-# This function is optionnal.
 #
-# Usage: ynh_exit_properly is used only by the helper ynh_abort_if_errors.
+# This function provide a way to clean some residual of installation that not managed by remove script.
-# You must not use it directly.
+#
+# It prints a warning to inform that the script was failed, and execute the ynh_clean_setup function if used in the app script
+#
 ynh_exit_properly () {
 	local exit_code=$?
 	if [ "$exit_code" -eq 0 ]; then
@@ -31,20 +30,23 @@ ynh_exit_properly () {
 	ynh_die	# Exit with error status
 }
 
-# Exit if an error occurs during the execution of the script.
+# Exits if an error occurs during the execution of the script.
 #
-# Stop immediatly the execution if an error occured or if a empty variable is used.
+# usage: ynh_abort_if_errors
-# The execution of the script is derivate to ynh_exit_properly function before exit.
+#
+# This configure the rest of the script execution such that, if an error occurs
+# or if an empty variable is used, the execution of the script stops
+# immediately and a call to `ynh_exit_properly` is triggered.
 #
-# Usage: ynh_abort_if_errors
 ynh_abort_if_errors () {
 	set -eu	# Exit if a command fail, and if a variable is used unset.
 	trap ynh_exit_properly EXIT	# Capturing exit signals on shell script
 }
 
-# Return the Debian release codename (i.e. jessie, stretch, etc.)
+# Fetch the Debian release codename
 #
 # usage: ynh_get_debian_release
+# | ret: The Debian release codename (i.e. jessie, stretch, ...)
 ynh_get_debian_release () {
 	echo $(lsb_release --codename --short)
-}
+}