devonfw#751: improved function documentation

documentation/functions.asciidoc

@@ -36,9 +36,11 @@ Output functions like xref:doEcho[] support backslash-escaped characters, for ex
 Display a question and ask the user if he wants to continue.
 In xref:doIsForce[force] or xref:doIsBatch[batch] mode, it will continue automatically.
 
+|=======================
 |*Param*|*Name*  |*Description*|
 |`$1`   |question|The question to display. Defaults to `Do you want to continue?`.
 |`$2`   |return  |If the user does not want to continue, this function will exit immediately by default. However, if `return` is passed the function will return 255 and the called can handle the program flow.
+|=======================
 
 === doConfirmWarning
 Passes all arguments to xref:doWarning[] to print as warning.
@@ -102,9 +104,11 @@ Handles the result of a command.
 Will print the operation (`$1`) as xref:doSuccess[success] message if exitCode (`$2`) is `0`.
 Otherwise it will pass it to xref:doFail[].
 
+|=======================
 |*Param*|*Name*    |*Description*|
 |`$1`   |operation |The operation that failed or succeeded.
 |`$2`   |exitCode  |`0` for sucess, otherwise the error code.
+|=======================
 
 === doSuccess
 Prints the given arguments as success message with according coloring (in green).
@@ -146,19 +150,23 @@ It will automatically pass mode options like xref:doIsBatch[batch] to the comman
 Further it xref:doError[prints an error message] if the commandlet was not successful.
 It will return with the exit code of the commandlet that has been invoked.
 
+|=======================
 |*Param*|*Name*     |*Description*|
 |`$1`   |commandlet |The devonfw-ide commandlet to call. E.g. `help` or `ide`.
 |`$2`-$n|args       |Any additional argument is passed to the specified commandlet.
+|=======================
 
 === doRunCommand
 Executes the given command (`$1`).
 If a a third parameter (`$3`) is provided, it has to point to an existing directory where to command will be executed and the function will return back to the original directory afterwards.
 It will use xref:doResult[] using the `message` (`$2`) to handle the result of the command execution (success or failure).
 
+|=======================
 |*Param*|*Name*  |*Description*|
 |`$1`   |command |The command to execute including all its parameters.
 |`$2`   |message |Optional description of the command. Will fall back to "run command" followed by a simplification of the command (`$1`).
 |`$3`   |dir     |Optional working directory where to execute the command.
+|=======================
 
 == Functions for IO operations (download, install, backup, extract, load, save)
 
@@ -177,6 +185,20 @@ Otherwise, the function will fail with an error message guiding the user to inst
 Downloads an artifact from the internet.
 If the URL is not provided as first argument, it will use the `mirrors` config to automatically determine the URL from the other arguments.
 
+|=======================
+|*Param*|*Name*  |*Description*|
+|`$1`   |URL     |The explicit URL to download from or `-` to compute in xref:doDownload[].
+|`$2`   |dir     |The optional target directory where to save the downloaded file.
+|`$3`   |name    |The name of the software to download.
+|`$4`   |version |The version of the software to download. May be omitted to download the latest version.
+|`$5`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
+|`$6`   |code    |The optional technical code used for specific software to compute download URL.
+|`$7`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
+|`$8`   |arch    |The optional architecture (e.g. x86_64).
+|`$9`   |ext     |The optional extension (e.g. 'tar.gz' or 'zip').
+|`$10`  |filename|The optional filename to save the downloaded file to.
+|=======================
+
 === doDownloadInternal
 Takes the URL as the first parameter, a temporary name for the file to be downloaded as the second, and the target directory in which the file is to be stored as the third parameter.
 Optionally, the name of the downloaded file can be given as a fourth parameter.
@@ -215,6 +237,21 @@ Following the doInstall call in the commandlet, the installation of the software
 
 * If parameters five through nine (edition, code, os, arch, and ext) are specified, they are passed directly to the doDownload function.
 
+|=======================
+|*Param*|*Name*  |*Description*|
+|`$1`   |URL     |The explicit URL to download from or `-` to compute in xref:doDownload[].
+|`$2`   |path    |The absolute target path where to install the software.
+|`$3`   |name    |The name of the software to install.
+|`$4`   |version |The version of the software to install. May be omitted to install the latest version.
+|`$5`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
+|`$6`   |code    |The optional technical code used for specific software to compute download URL.
+|`$7`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
+|`$8`   |arch    |The optional architecture (e.g. x86_64).
+|`$9`   |ext     |The optional extension (e.g. 'tar.gz' or 'zip').
+|`$10`  |repo    |The optional software repository.
+|`$11`  |noUnpack|The optional argument to ignore extracting downloaded files (if not empty extracting will be skipped)
+|=======================
+
 === doInstallWithPackageManager
 Called with a list of installation options for various (non windows) operating systems.
 For each provided installer option it will check if that installer (e.g. `apt-get`, `yum`, `apk`, `brew`) is present.