improve doc generator, introduce verbose_description property

diff --git a/src/PVE/JSONSchema.pm b/src/PVE/JSONSchema.pm
index f90d98c590f279a6461493562f2cee9020be71b7..5131e4dc07b7ed27c855950c681e4c81b79fffc5 100644 (file)
--- a/src/PVE/JSONSchema.pm
+++ b/src/PVE/JSONSchema.pm
@@ -978,6 +978,11 @@ my $default_schema_noref = {
            optional => 1,
            description => "This provides a description of the purpose the instance property. The value can be a string or it can be an object with properties corresponding to various different instance languages (with an optional default property indicating the default description).",
        },
+       verbose_description => {
+           type => "string",
+           optional => 1,
+           description => "This provides a more verbose description.",
+       },
        format_description => {
            type => "string",
            optional => 1,
@@ -1651,6 +1656,8 @@ sub print_property_string {
 sub schema_get_type_text {
     my ($phash) = @_;
 
+    my $type = $phash->{type} || 'string';
+
     if ($phash->{typetext}) {
        return $phash->{typetext};
     } elsif ($phash->{format_description}) {
@@ -1659,15 +1666,15 @@ sub schema_get_type_text {
        return "(" . join(' | ', sort @{$phash->{enum}}) . ")";
     } elsif ($phash->{pattern}) {
        return $phash->{pattern};
-    } elsif ($phash->{type} eq 'integer' || $phash->{type} eq 'number') {
+    } elsif ($type eq 'integer' || $type eq 'number') {
        if (defined($phash->{minimum}) && defined($phash->{maximum})) {
-           return "$phash->{type} ($phash->{minimum} - $phash->{maximum})";
+           return "$type ($phash->{minimum} - $phash->{maximum})";
        } elsif (defined($phash->{minimum})) {
-           return "$phash->{type} ($phash->{minimum} - N)";
+           return "$type ($phash->{minimum} - N)";
        } elsif (defined($phash->{maximum})) {
-           return "$phash->{type} (-N - $phash->{maximum})";
+           return "$type (-N - $phash->{maximum})";
        }
-    } elsif ($phash->{type} eq 'string') {
+    } elsif ($type eq 'string') {
        if (my $format = $phash->{format}) {
            $format = get_format($format) if ref($format) ne 'HASH';
            if (ref($format) eq 'HASH') {
@@ -1676,8 +1683,6 @@ sub schema_get_type_text {
        }
     }
 
-    my $type = $phash->{type} || 'string';
-
     return $type;
 }
 

diff --git a/src/PVE/RESTHandler.pm b/src/PVE/RESTHandler.pm
index 3b9511419ceccc3dbb81d15812b4fb2798ec73b4..0b8b81c6d740854c72e5b42fc2709de513b786d3 100644 (file)
--- a/src/PVE/RESTHandler.pm
+++ b/src/PVE/RESTHandler.pm
@@ -418,6 +418,11 @@ my $get_property_description = sub {
 
     my $descr = $phash->{description} || "no description available";
 
+    if ($phash->{verbose_description} &&
+       ($style eq 'config' || $style eq 'config-sub')) {
+       $descr = $phash->{verbose_description};
+    }
+
     chomp $descr;
 
     my $type = PVE::JSONSchema::schema_get_type_text($phash);
@@ -439,6 +444,8 @@ my $get_property_description = sub {
 
        if ($style eq 'config') {
            $res .= "`$name`: ";
+       } elsif ($style eq 'config-sub') {
+           $res .= "`$name`=";
        } elsif ($style eq 'arg') {
            $res .= "`-$name` ";
        } elsif ($style eq 'fixed') {
@@ -452,9 +459,14 @@ my $get_property_description = sub {
        if (defined(my $dv = $phash->{default})) {
            $res .= "(default=`$dv`)";
        }
-       $res .= "::\n\n";
 
-       my $wdescr = Text::Wrap::wrap('', '', ($descr));
+       if ($style eq 'config-sub') {
+           $res .= ";;\n\n";
+       } else {
+           $res .= "::\n\n";
+       }
+
+       my $wdescr = $descr;
        chomp $wdescr;
        $wdescr =~ s/^$/+/mg;
 
@@ -629,8 +641,7 @@ sub dump_properties {
        my $phash = $prop->{$k};
 
        next if defined($filterFn) && &$filterFn($k, $phash);
-
-       my $type = $phash->{type} || 'string';
+       next if $phash->{alias};
 
        my $base = $k;
        if ($k =~ m/^([a-z]+)(\d+)$/) {
@@ -643,6 +654,20 @@ sub dump_properties {
        }
 
        $raw .= &$get_property_description($base, $style, $phash, $format, 0);
+
+       next if $style ne 'config';
+
+       my $prop_fmt = $phash->{format};
+       next if !$prop_fmt;
+
+       if (ref($prop_fmt) ne 'HASH') {
+           $prop_fmt = PVE::JSONSchema::get_format($prop_fmt);
+       }
+
+       next if !(ref($prop_fmt) && (ref($prop_fmt) eq 'HASH'));
+
+       $raw .= dump_properties($prop_fmt, $format, 'config-sub')
+       
     }
 
     return $raw;