add docs and fix docblock

Author: Jamie Hannaford

doc/services/object-store/v1/objects.rst

@@ -52,10 +52,31 @@ returned. If you would like to access all of the remote state of a collection it
 If you have a large collection of $object, this will slow things down because you're issuing a HEAD request per object.
 
 Create an object
-------------
+----------------
+
+When creating an object, you can upload its content according to a string representation:
 
 .. sample:: object_store/v1/objects/create.php
 
+If that is not optimal or convenient, you can use a stream instead. Any instance of ``\Psr\Http\Message\StreamInterface``
+is acceptable. For example, to use a normal Guzzle stream:
+
+.. sample:: object_store/v1/objects/create_from_stream.php
+
+Create a large object (over 5GB)
+--------------------------------
+
+For large objects (those over 5GB), you will need to use a concept in Swift called Dynamic Large Objects (DLO). When
+uploading, this is what happens under the hood:
+
+1. The large file is separated into smaller segments
+2. Each segment is uploaded
+3. A manifest file is created which, when requested by clients, will concatenate all the segments as a single file
+
+To upload a DLO, you need to call:
+
+.. sample:: object_store/v1/objects/create_large_object.php
+
 Copy object
 -----------
 

samples/object_store/v1/objects/create_from_stream.php

@@ -0,0 +1,28 @@
+<?php
+
+require 'vendor/autoload.php';
+
+use GuzzleHttp\Psr7\Stream;
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}'
+    ],
+    'scope'   => ['project' => ['id' => '{projectId}']]
+]);
+
+// You can use any instance of \Psr\Http\Message\StreamInterface
+$stream = new Stream(fopen('/path/to/object.txt', 'r'));
+
+$options = [
+    'name'   => '{objectName}',
+    'stream' => $stream,
+];
+
+/** @var \OpenStack\ObjectStore\v1\Models\Object $object */
+$object = $openstack->objectStoreV1()
+    ->getContainer('{containerName}')
+    ->createObject($options);

samples/object_store/v1/objects/create_large_object.php

@@ -0,0 +1,33 @@
+<?php
+
+require 'vendor/autoload.php';
+
+use Guzzle\Stream\Stream;
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}'
+    ],
+    'scope'   => ['project' => ['id' => '{projectId}']]
+]);
+
+$options = [
+    'name'   => 'object_name.txt',
+    'stream' => new Stream(fopen('/path/to/large_object.mov', 'r')),
+];
+
+// optional: specify the size of each segment in bytes
+$options['segmentSize'] = 1073741824;
+
+// optional: specify the container where the segments live. This does not necessarily have to be the
+// same as the container which holds the manifest file
+$options['segmentContainer'] = 'test_segments';
+
+
+/** @var \OpenStack\ObjectStore\v1\Models\Object $object */
+$object = $openstack->objectStoreV1()
+                    ->getContainer('test')
+                    ->createLargeObject($options);

src/Networking/v2/Service.php

@@ -117,7 +117,7 @@ public function listSubnets(array $options = [])
     /**
      * Create a new port resource.
      *
-     * @param array $options {@see \OpenStack\Networking\v2\Api::postPort}
+     * @param array $options {@see \OpenStack\Networking\v2\Api::postPorts}
      *
      * @return Port
      */