Re: [pmg-devel] [PATCH pmg-api] API: Mailtracker: add values to rstatus and dstatus description

[Mira Limbeck <m.limbeck@proxmox.com>]

some comments inline

On 8/12/21 5:30 PM, Aaron Lauterer wrote:
> The possible values were only documented within the source code. Having
> them as part of the API description will help people wanting to use the
> tracker API endpoint interpreting the results.
>
> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
> ---
>   src/PMG/API2/MailTracker.pm | 14 ++++++++++++--
>   1 file changed, 12 insertions(+), 2 deletions(-)
>
> diff --git a/src/PMG/API2/MailTracker.pm b/src/PMG/API2/MailTracker.pm
> index 187decf..952abc8 100644
> --- a/src/PMG/API2/MailTracker.pm
> +++ b/src/PMG/API2/MailTracker.pm
> @@ -38,6 +38,14 @@ my $statmap = {
>       Q => 'quarantine',
>   };
>   
> +my $print_statmap = sub {
> +    my $map = "";
> +    foreach my $key (sort keys %$statmap) {
> +	$map .= "$key: $statmap->{$key}\n";
> +    }
> +    return $map;
> +};
> +
>   my $run_pmg_log_tracker = sub {
>       my ($args, $includelog) = @_;
>   
> @@ -247,13 +255,15 @@ my $email_log_property_desc = {
>   	type => 'integer',
>       },
>       dstatus => {
> -	description => "Delivery status.",
> +	description => "Delivery status. Can be one of the following values:\n" .
> +	$print_statmap->(),

Maybe, instead of adding it to the description, change the type from 
`string` to `enum` with the few possible values.

This should result in a nice overview of the possible return values in 
the API viewer.

>   	type => 'string',
>   	minLength => 1,
>   	maxLength => 1,
>       },
>       rstatus => {
> -	description => "Delivery status of relayed mail.",
> +	description => "Delivery status of relayed mail. Can be one of the " .
> +	"following values:\n" . $print_statmap->(),
Same here, as only `2`, `4` and `5` are valid `rstatus` values.
>   	type => 'string',
>   	minLength => 1,
>   	maxLength => 1,