From d06a69ab1154d516b940c41b6f0bdca7a97f0fec Mon Sep 17 00:00:00 2001
From: Marius Gavrilescu <marius@ieval.ro>
Date: Mon, 21 Sep 2015 20:18:13 +0300
Subject: [PATCH] Improve POD

---
 lib/WebService/Scaleway.pm | 42 ++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/lib/WebService/Scaleway.pm b/lib/WebService/Scaleway.pm
index 9c327e6..4545952 100644
--- a/lib/WebService/Scaleway.pm
+++ b/lib/WebService/Scaleway.pm
@@ -207,7 +207,10 @@ WebService::Scaleway - Perl interface to Scaleway cloud server provider API
   my $ip = $sw->create_ip($org);
   my $vol = $sw->create_volume('testvol', $org, 'l_ssd', 50_000_000_000);
   my ($debian) = grep { $_->name =~ /debian jessie/i } $sw->images;
-  my $srv = $sw->create_server('testsrv', $org, $debian, {1 => {%$vol}});
+  my $srv = $sw->create_server('testsrv', $org, $debian, {1 => $vol->id});
+
+  # Now we have a server, an IP, and two volumes (the root volume with
+  # Debian Jessie, and the extra volume we just created).
 
   # Change the server name
   $srv->{name} = 'Debian';
@@ -312,9 +315,13 @@ Official documentation: L<https://developer.scaleway.com/#security-groups-manage
 
 =head2 Retrieving resources
 
-These methods take the id of a resource and return the resource as a
+These methods take the ID of a resource and return the resource as a
 blessed hashref as described in the previous section.
 
+You can pass a blessed hashref instead of a resource ID, and you'll
+get a fresh version of the object passed. Useful if something updated
+the object in the meantime.
+
 There is no difference between B<resource>(I<$id>) and
 B<get_resource>(I<$id>).
 
@@ -378,8 +385,9 @@ Official documentation: L<https://developer.scaleway.com/#security-groups-operat
 
 =head2 Deleting resources
 
-These methods take the id of a resource and delete it. They do not
-return anything.
+These methods take the ID of a resource and delete it. They do not
+return anything. You can pass a blessed hashref instead of a resource
+ID.
 
 =over
 
@@ -461,8 +469,8 @@ resource and return it as a blessed hashref as described in
 L</"Listing resources">.
 
 When using positional parameters, you can pass a resource in blessed
-hashref format where a resource ID is expected. The function will call
-C<< ->id >> on the resouce automatically.
+hashref format where a resource ID is expected, unless the method's
+documentation says otherwise.
 
 Most of these methods require an organization ID. You can obtain it
 with the B<organizations> method described above.
@@ -489,11 +497,23 @@ Creates and returns a new server.
 
 I<$name> is the server name. I<$organization> is the organization ID.
 I<$image> is the image ID. I<$volumes> is a "sparse array" (hashref
-from indexes to volumes, indexed from 1) of volumes. I<$tags> is an
-optional arrayref of tags.
-
-Note that the volumes must be unblessed hashrefs. If I<$vol> is a
-volume, you can use this idiom: C<< $volumes = {1 => {%$vol}} >>.
+from indexes to volume IDs, indexed from 1) of B<extra> volumes (that
+is, volumes other than the root volume). I<$tags> is an optional
+arrayref of tags.
+
+For the I<$volumes> parameter you can pass hashrefs that describe
+volumes instead of volume IDs. This will create new volumes. The
+hashrefs are (presumably) passed to B<create_volume>. An example
+inspired by the official documentation:
+
+  $volumes = { 1 => {
+    name         => "vol_demo",
+    organization => "ecc1c86a-eabb-43a7-9c0a-77e371753c0a",
+    size         => 10_000_000_000,
+    volume_type  => "l_sdd",
+  }};
+
+Note that there B<may not> be any blessed hashrefs inside I<$volumes>.
 
 Official documentation: L<https://developer.scaleway.com/#servers-servers-get>.
 
-- 
2.30.2