Misc fixes in helpers comments to fix/improve autogenerated doc

data/helpers.d/apt

@@ -194,13 +194,13 @@ ynh_package_install_from_equivs () {
 }
 
 # Define and install dependencies with a equivs control file
+#
 # This helper can/should only be called once per app
 #
+# example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
+#
 # usage: ynh_install_app_dependencies dep [dep [...]]
-# | arg: dep - the package name to install in dependence
-#   You can give a choice between some package with this syntax : "dep1|dep2"
-#   Example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
-#   This mean in the dependence tree : dep1 & dep2 & (dep3 | dep4 | dep5)
+# | arg: dep - the package name to install in dependence. Writing "dep3|dep4|dep5" can be used to specify alternatives. For example : dep1 dep2 "dep3|dep4|dep5" will require to install dep1 and dep 2 and (dep3 or dep4 or dep5).
 #
 # Requires YunoHost version 2.6.4 or higher.
 ynh_install_app_dependencies () {

data/helpers.d/backup

@@ -4,8 +4,7 @@ CAN_BIND=${CAN_BIND:-1}
 
 # Add a file or a directory to the list of paths to backup
 #
-# Note: this helper could be used in backup hook or in backup script inside an
-# app package
+# This helper can be used both in a system backup hook, and in an app backup script
 #
 # Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it
 # creates the parent destination directory
@@ -154,7 +153,7 @@ ynh_backup() {
     mkdir -p $(dirname "$YNH_BACKUP_DIR/${dest_path}")
 }
 
-# Restore all files linked to the restore hook or to the restore app script
+# Restore all files that were previously backuped in a core backup script or app backup script
 #
 # usage: ynh_restore
 #
@@ -317,11 +316,10 @@ ynh_store_file_checksum () {
 }
 
 # Verify the checksum and backup the file if it's different
+# 
 # This helper is primarily meant to allow to easily backup personalised/manually
 # modified config files.
 #
-# $app should be defined when calling this helper
-#
 # usage: ynh_backup_if_checksum_is_different --file=file
 # | arg: -f, --file - The file on which the checksum test will be perfomed.
 # | ret: the name of a backup file, or nothing

data/helpers.d/logging

@@ -1,6 +1,7 @@
 #!/bin/bash
 
 # Print a message to stderr and exit
+#
 # usage: ynh_die --message=MSG [--ret_code=RETCODE]
 #
 # Requires YunoHost version 2.4.0 or higher.
@@ -97,9 +98,11 @@ ynh_print_err () {
 
 # Execute a command and print the result as an error
 #
-# usage: ynh_exec_err command to execute
-# usage: ynh_exec_err "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_exec_err your_command
+# usage: ynh_exec_err "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
 # If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
@@ -111,9 +114,11 @@ ynh_exec_err () {
 
 # Execute a command and print the result as a warning
 #
-# usage: ynh_exec_warn command to execute
-# usage: ynh_exec_warn "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_exec_warn your_command
+# usage: ynh_exec_warn "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
 # If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
@@ -125,9 +130,11 @@ ynh_exec_warn () {
 
 # Execute a command and force the result to be printed on stdout
 #
-# usage: ynh_exec_warn_less command to execute
-# usage: ynh_exec_warn_less "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_exec_warn_less your_command
+# usage: ynh_exec_warn_less "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
 # If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
@@ -139,9 +146,11 @@ ynh_exec_warn_less () {
 
 # Execute a command and redirect stdout in /dev/null
 #
-# usage: ynh_exec_quiet command to execute
-# usage: ynh_exec_quiet "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_exec_quiet your_command
+# usage: ynh_exec_quiet "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
 # If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
@@ -153,9 +162,11 @@ ynh_exec_quiet () {
 
 # Execute a command and redirect stdout and stderr in /dev/null
 #
-# usage: ynh_exec_fully_quiet command to execute
-# usage: ynh_exec_fully_quiet "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_exec_fully_quiet your_command
+# usage: ynh_exec_fully_quiet "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
 # If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
@@ -168,6 +179,7 @@ ynh_exec_fully_quiet () {
 # Remove any logs for all the following commands.
 #
 # usage: ynh_print_OFF
+#
 # WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging.
 #
 # Requires YunoHost version 3.2.0 or higher.
@@ -186,16 +198,7 @@ ynh_print_ON () {
 	echo ynh_print_ON > /dev/null
 }
 
-# Print a message as INFO and show progression during an app script
-#
-# usage: ynh_script_progression --message=message [--weight=weight] [--time]
-# | arg: -m, --message= - The text to print
-# | arg: -w, --weight=  - The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script.
-# | arg: -t, --time=    - Print the execution time since the last call to this helper. Especially usefull to define weights.
-# The execution time is given for the duration since the previous call. So the weight should be applied to this previous call.
-# | arg: -l, --last=    - Use for the last call of the helper, to fill te progression bar.
-#
-# Requires YunoHost version 3.5.0 or higher.
+# Initial definitions for ynh_script_progression
 increment_progression=0
 previous_weight=0
 max_progression=-1
@@ -207,6 +210,16 @@ progress_string1="++++++++++++++++++++"
 progress_string0="...................."
 # Define base_time when the file is sourced
 base_time=$(date +%s)
+
+# Print a progress bar showing the progression of an app script
+#
+# usage: ynh_script_progression --message=message [--weight=weight] [--time]
+# | arg: -m, --message= - The text to print
+# | arg: -w, --weight=  - The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script.
+# | arg: -t, --time=    - Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call.
+# | arg: -l, --last=    - Use for the last call of the helper, to fill te progression bar.
+#
+# Requires YunoHost version 3.5.0 or higher.
 ynh_script_progression () {
 	set +x
 	# Declare an array to define the options of this helper.
@@ -350,9 +363,12 @@ ynh_debug () {
 
 # Execute a command and print the result as debug
 #
-# usage: ynh_debug_exec command to execute
-# usage: ynh_debug_exec "command to execute | following command"
-# In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
+# usage: ynh_debug_exec your_command
+# usage: ynh_debug_exec "your_command | other_command"
+#
+# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
+#
+# If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
 #
 # | arg: command - command to execute
 #

data/helpers.d/nodejs

@@ -60,9 +60,7 @@ ynh_use_nodejs () {
 # ynh_install_nodejs will install the version of node provided as argument by using n.
 #
 # usage: ynh_install_nodejs --nodejs_version=nodejs_version
-# | arg: -n, --nodejs_version - Version of node to install.
-#        If possible, prefer to use major version number (e.g. 8 instead of 8.10.0).
-#        The crontab will handle the update of minor versions when needed.
+# | arg: -n, --nodejs_version - Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed.
 #
 # Requires YunoHost version 2.7.12 or higher.
 ynh_install_nodejs () {

data/helpers.d/postgresql

@@ -4,8 +4,9 @@ PSQL_ROOT_PWD_FILE=/etc/yunohost/psql
 
 # Open a connection as a user
 #
-# example: ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"
-# example: ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
+# examples: 
+#    ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"
+#    ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
 #
 # usage: ynh_psql_connect_as --user=user --password=password [--database=database]
 # | arg: -u, --user - the user name to connect as

data/helpers.d/systemd

@@ -74,11 +74,7 @@ ynh_remove_systemd_config () {
 # usage: ynh_systemd_action [-n service_name] [-a action] [ [-l "line to match"] [-p log_path] [-t timeout] [-e length] ]
 # | arg: -n, --service_name= - Name of the service to start. Default : $app
 # | arg: -a, --action=       - Action to perform with systemctl. Default: start
-# | arg: -l, --line_match=   - Line to match - The line to find in the log to attest the service have finished to boot.
-#                              If not defined it don't wait until the service is completely started.
-#                              WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your
-#                                `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure
-#                                of the script. The script will then hang forever.
+# | arg: -l, --line_match=   - Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started. WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure of the script. The script will then hang forever.
 # | arg: -p, --log_path=     - Log file - Path to the log file. Default : /var/log/$app/$app.log
 # | arg: -t, --timeout=      - Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.
 # | arg: -e, --length=       - Length of the error log : Default : 20

data/helpers.d/utils

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Manage a fail of the script
+# Handle script crashes / failures
 #
 # [internal]
 #
@@ -421,6 +421,7 @@ ynh_read_manifest () {
 }
 
 # Read the upstream version from the manifest
+#
 # The version number in the manifest is defined by <upstreamversion>~ynh<packageversion>
 # For example : 4.3-2~ynh3
 # This include the number before ~ynh
@@ -444,6 +445,7 @@ ynh_app_upstream_version () {
 }
 
 # Read package version from the manifest
+#
 # The version number in the manifest is defined by <upstreamversion>~ynh<packageversion>
 # For example : 4.3-2~ynh3
 # This include the number after ~ynh
@@ -467,6 +469,7 @@ ynh_app_package_version () {
 }
 
 # Checks the app version to upgrade with the existing app version and returns:
+#
 # - UPGRADE_APP if the upstream app version has changed
 # - UPGRADE_PACKAGE if only the YunoHost package has changed
 #

doc/generate_helper_doc.py

@@ -70,6 +70,18 @@ class Parser():
                     # We're still in a comment bloc
                     assert line.startswith("# ") or line == "#", malformed_error(i)
                     current_block["comments"].append(line[2:])
+                elif line.strip() == "":
+                    # Well eh that was not an actual helper definition ... start over ?
+                    current_reading = "void"
+                    current_block = { "name": None,
+                                     "line": -1,
+                                     "comments": [],
+                                     "code": []
+                                     }
+                elif not (line.endswith("{") or line.endswith("()")):
+                    # Well we're not actually entering a function yet eh
+                    # (c.f. global vars)
+                    pass
                 else:
                     # We're getting out of a comment bloc, we should find
                     # the name of the function
@@ -79,8 +91,6 @@ class Parser():
                     # Then we expect to read the function
                     current_reading = "code"
 
-                continue
-
             elif current_reading == "code":
 
                 if line == "}":
@@ -97,7 +107,6 @@ class Parser():
                                       "code": [] }
                 else:
                     current_block["code"].append(line)
-                    pass
 
                 continue