Merge pull request #440 from YunoHost/clean-helper-doc

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/filesystem

@@ -136,6 +136,8 @@ ynh_restore () {
 
 # Return the path in the archive where has been stocked the origin path
 #
+# [internal]
+#
 # usage: _get_archive_path ORIGIN_PATH
 _get_archive_path () {
     # For security reasons we use csv python library to read the CSV
@@ -203,6 +205,9 @@ ynh_restore_file () {
 }
 
 # Deprecated helper since it's a dangerous one!
+#
+# [internal]
+#
 ynh_bind_or_cp() {
     local AS_ROOT=${3:-0}
     local NO_ROOT=0
@@ -213,6 +218,8 @@ ynh_bind_or_cp() {
 
 # Create a directory under /tmp
 #
+# [internal]
+#
 # Deprecated helper
 #
 # usage: ynh_mkdir_tmp

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

@@ -35,6 +35,8 @@ ynh_mysql_execute_file_as_root() {
 
 # Create a database and grant optionnaly privilegies to a user
 #
+# [internal]
+#
 # usage: ynh_mysql_create_db db [user [pwd]]
 # | arg: db - the database name to create
 # | arg: user - the user to grant privilegies
@@ -56,6 +58,8 @@ ynh_mysql_create_db() {
 
 # Drop a database
 #
+# [internal]
+#
 # If you intend to drop the database *and* the associated user,
 # consider using ynh_mysql_remove_db instead.
 #
@@ -78,6 +82,8 @@ ynh_mysql_dump_db() {
 
 # Create a user
 #
+# [internal]
+#
 # usage: ynh_mysql_create_user user pwd [host]
 # | arg: user - the user name to create
 # | arg: pwd - the password to identify user by
@@ -90,7 +96,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';") ]]
@@ -103,6 +109,8 @@ function ynh_mysql_user_exists()
 
 # Drop a user
 #
+# [internal]
+#
 # usage: ynh_mysql_drop_user user
 # | arg: user - the user name to drop
 ynh_mysql_drop_user() {
@@ -153,7 +161,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/package

@@ -26,6 +26,8 @@ ynh_package_version() {
 
 # APT wrapper for non-interactive operation
 #
+# [internal]
+#
 # usage: ynh_apt update
 ynh_apt() {
     DEBIAN_FRONTEND=noninteractive sudo apt-get -y -qq $@
@@ -73,6 +75,8 @@ ynh_package_autopurge() {
 
 # Build and install a package from an equivs control file
 #
+# [internal]
+#
 # example: generate an empty control file with `equivs-control`, adjust its
 #          content and use helper to build and install the package:
 #              ynh_package_install_from_equivs /path/to/controlfile

data/helpers.d/print

@@ -6,7 +6,11 @@ ynh_die() {
 }
 
 # Ignore the yunohost-cli log to prevent errors with conditionals commands
+#
+# [internal]
+#
 # usage: ynh_no_log COMMAND
+#
 # Simply duplicate the log, execute the yunohost command and replace the log without the result of this command
 # It's a very badly hack...
 ynh_no_log() {

data/helpers.d/system

@@ -1,18 +1,19 @@
 # Manage a fail of the script
 #
-# Print a warning to inform that the script was failed
+# [internal]
-# Execute the ynh_clean_setup function if used in the app script
 #
-# usage of ynh_clean_setup function
+# usage: 
-# This function provide a way to clean some residual of installation that not managed by remove script.
+# ynh_exit_properly is used only by the helper ynh_abort_if_errors.
-# To use it, simply add in your script:
+# You should not use it directly.
+# Instead, add to 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 +32,24 @@ 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_clean_setup` is triggered if it has been
+# defined by your script.
 #
-# 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)
 }