From: Dietmar Maurer <dietmar@proxmox.com>
Date: Thu, 19 May 2016 11:11:26 +0000 (+0200)
Subject: improve doc generator, introduce verbose_description property
X-Git-Url: https://git.proxmox.com/?p=pve-common.git;a=commitdiff_plain;h=32f8e0c75bab20a363192f5bd5d0b7037fd7f918

improve doc generator, introduce verbose_description property
---

diff --git a/src/PVE/JSONSchema.pm b/src/PVE/JSONSchema.pm
index f90d98c..5131e4d 100644
--- 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 3b95114..0b8b81c 100644
--- 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;