Merge pull request #2 from lukaspawlik/feature/WM-334

WM-334

includes/class-windows-azure-config-provider.php

@@ -47,7 +47,9 @@ class Windows_Azure_Config_Provider {
 	/**
 	 * Return account credentials.
 	 *
-	 * @return array
+	 * @since 4.0.0
+	 *
+	 * @return array Account credentials.
 	 */
 	static public function get_account_credentials() {
 		static $credentials;

includes/class-windows-azure-file-contents-provider.php

@@ -41,82 +41,105 @@
  * @copyright Microsoft Open Technologies, Inc.
  * @license   New BSD license, (http://www.opensource.org/licenses/bsd-license.php)
  * @link      http://www.microsoft.com
+ * @since     4.0.0
  */
 class Windows_Azure_File_Contents_Provider {
 
 	/**
 	 * Chunk size.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @const int
 	 */
 	const CHUNK_SIZE = 4194304;
 
 	/**
 	 * Max Azure REST API request length.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @const int
 	 */
 	const MAX_CHUNK_SIZE = 4194304;
 
 	/**
 	 * File path.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var string
 	 */
 	protected $_file_path;
 
 	/**
 	 * Whether class file is a file and is readable.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var bool
 	 */
 	protected $_is_valid;
 
 	/**
 	 * File system access.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var bool|WP_Filesystem_Base
 	 */
 	protected $_wp_filesystem;
 
 	/**
 	 * Chunk size.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var int
 	 */
 	protected $_chunk_size;
 
 	/**
 	 * Current stream position.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var int
 	 */
 	protected $_position;
 
 	/**
 	 * File contents for non-stream providers.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var string
 	 */
 	protected $_contents;
 
 	/**
 	 * File handle.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var resource
 	 */
 	protected $_handle;
 
 	/**
 	 * Whether WP Filesystem can read from the stream or not.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var bool
 	 */
 	protected $_stream_reader;
 
 	/**
 	 * Windows_Azure_File_Contents_Provider constructor.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @param string $file_path  File path.
 	 * @param int    $chunk_size Chunk size.
 	 */
@@ -131,7 +154,9 @@ public function __construct( $file_path, $chunk_size = self::CHUNK_SIZE ) {
 	/**
 	 * Whether class file is valid.
 	 *
-	 * @return bool|WP_Error
+	 * @since 4.0.0
+	 *
+	 * @return bool|WP_Error Whether this class provides access to file or not.
 	 */
 	public function is_valid() {
 		if ( ! $this->_wp_filesystem ) {
@@ -148,6 +173,8 @@ public function is_valid() {
 	/**
 	 * Rewind stream to the beginning.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @return void
 	 */
 	public function rewind() {
@@ -160,7 +187,9 @@ public function rewind() {
 	/**
 	 * Get chunk contents.
 	 *
-	 * @return string|bool
+	 * @since 4.0.0
+	 *
+	 * @return string|bool Chunk data or false if end of the stream.
 	 */
 	public function get_chunk() {
 		if ( 0 === $this->_position ) {
@@ -189,6 +218,8 @@ public function get_chunk() {
 	/**
 	 * Close stream handlers if possible.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @return void
 	 */
 	public function close() {

includes/class-windows-azure-filesystem-access-provider.php

@@ -41,13 +41,16 @@
  * @copyright Microsoft Open Technologies, Inc.
  * @license   New BSD license, (http://www.opensource.org/licenses/bsd-license.php)
  * @link      http://www.microsoft.com
+ * @since     4.0.0
  */
 class Windows_Azure_Filesystem_Access_Provider {
 
 	/**
 	 * Return WordPress Filesystem access class.
 	 *
-	 * @return bool|WP_Filesystem_Base
+	 * @since 4.0.0
+	 *
+	 * @return bool|WP_Filesystem_Base WP_Filesystem instance of false on failure.
 	 */
 	static public function get_provider() {
 		global $wp_filesystem;

includes/class-windows-azure-generic-list-response.php

@@ -41,65 +41,91 @@
  * @copyright Microsoft Open Technologies, Inc.
  * @license   New BSD license, (http://www.opensource.org/licenses/bsd-license.php)
  * @link      http://www.microsoft.com
+ * @since     4.0.0
  */
 abstract class Windows_Azure_Generic_List_Response implements Iterator {
 
 	/**
 	 * Current position.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var int
 	 */
 	protected $_position = 0;
 
 	/**
 	 * List of containers.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var array
 	 */
 	protected $_items;
 
 	/**
 	 * REST client.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var Windows_Azure_Rest_Api_Client
 	 */
 	protected $_rest_client;
 
 	/**
 	 * Max containers results per one request.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var int
 	 */
 	protected $_max_results;
 
 	/**
 	 * Next collection marker.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var string
 	 */
 	protected $_next_marker;
 
 	/**
 	 * Search prefix.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @var string
 	 */
 	protected $_prefix;
 
+	/**
+	 * Generic path value.
+	 *
+	 * @since 4.0.0
+	 *
+	 * @var string
+	 */
+	protected $_path;
+
 	/**
 	 * Windows_Azure_List_Containers_Response constructor.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @param array                         $rest_response Rest response.
 	 * @param Windows_Azure_Rest_Api_Client $client        REST client.
 	 * @param string                        $prefix        Search prefix.
 	 * @param int                           $max_results   Max results per one request.
+	 * @param string                        $path          Optional request path.
 	 */
-	public function __construct( array $rest_response, Windows_Azure_Rest_Api_Client $client, $prefix = '', $max_results = Windows_Azure_Rest_Api_Client::API_REQUEST_BULK_SIZE ) {
+	public function __construct( array $rest_response, Windows_Azure_Rest_Api_Client $client, $prefix = '', $max_results = Windows_Azure_Rest_Api_Client::API_REQUEST_BULK_SIZE, $path = '' ) {
 		$this->_position    = 0;
 		$this->_items       = array();
 		$this->_rest_client = $client;
 		$this->_max_results = $max_results;
 		$this->_prefix      = $prefix;
+		$this->_path        = $path;
 
 		if ( isset( $rest_response['NextMarker'] ) && ! empty( $rest_response['NextMarker'] ) ) {
 			$this->_next_marker = $rest_response['NextMarker'];
@@ -109,9 +135,10 @@ public function __construct( array $rest_response, Windows_Azure_Rest_Api_Client
 
 	/**
 	 * Return the current element
-	 * @link  http://php.net/manual/en/iterator.current.php
+	 *
+	 * @since 4.0.0
+	 *
 	 * @return mixed Can return any type.
-	 * @since 5.0.0
 	 */
 	public function current() {
 		if ( ! isset( $this->_items[ $this->_position ] ) ) {
@@ -123,13 +150,14 @@ public function current() {
 
 	/**
 	 * Move forward to next element
-	 * @link  http://php.net/manual/en/iterator.next.php
-	 * @return void Any returned value is ignored.
-	 * @since 5.0.0
+	 *
+	 * @since 4.0.0
+	 *
+	 * @return void
 	 */
 	public function next() {
 		if ( ! empty( $this->_next_marker ) && ( $this->_position === count( $this->_items ) - 1 ) ) {
-			$lazy_loaded = $this->_list_items( $this->_prefix, $this->_max_results, $this->_next_marker );
+			$lazy_loaded = $this->_list_items( $this->_prefix, $this->_max_results, $this->_next_marker, $this->_path );
 			if ( $lazy_loaded instanceof Windows_Azure_Generic_List_Response ) {
 				$this->_items       = array_merge( $this->_items, $lazy_loaded->get_all() );
 				$this->_next_marker = $lazy_loaded->get_next_marker();
@@ -141,39 +169,43 @@ public function next() {
 
 	/**
 	 * Return the key of the current element
-	 * @link  http://php.net/manual/en/iterator.key.php
+	 *
+	 * @since 4.0.0
+	 *
 	 * @return mixed scalar on success, or null on failure.
-	 * @since 5.0.0
 	 */
 	public function key() {
 		return $this->_position;
 	}
 
 	/**
 	 * Checks if current position is valid
-	 * @link  http://php.net/manual/en/iterator.valid.php
-	 * @return boolean The return value will be casted to boolean and then evaluated.
-	 * Returns true on success or false on failure.
-	 * @since 5.0.0
+	 *
+	 * @since 4.0.0
+	 *
+	 * @return boolean The return value will be casted to boolean and then evaluated. Returns true on success or false on failure.
 	 */
 	public function valid() {
 		return isset( $this->_items[ $this->_position ] );
 	}
 
 	/**
 	 * Rewind the Iterator to the first element
-	 * @link  http://php.net/manual/en/iterator.rewind.php
-	 * @return void Any returned value is ignored.
-	 * @since 5.0.0
+	 *
+	 * @since 4.0.0
+	 *
+	 * @return void
 	 */
 	public function rewind() {
 		$this->_position = 0;
 	}
 
 	/**
-	 * Return all containers.
+	 * Return all items.
 	 *
-	 * @return array
+	 * @since 4.0.0
+	 *
+	 * @return array Array containing all items.
 	 */
 	public function get_all() {
 		return $this->_items;
@@ -182,7 +214,9 @@ public function get_all() {
 	/**
 	 * Return next marker.
 	 *
-	 * @return null|string
+	 * @since 4.0.0
+	 *
+	 * @return null|string Next portion of data marker.
 	 */
 	public function get_next_marker() {
 		return $this->_next_marker;
@@ -191,13 +225,16 @@ public function get_next_marker() {
 	/**
 	 * Empty stub for lazy loading of items.
 	 *
+	 * @since 4.0.0
+	 *
 	 * @param string $prefix      Search prefix.
 	 * @param int    $max_results Max API listing results.
 	 * @param string $next_marker Offset marker.
+	 * @param string $path        Optional request path.
 	 *
-	 * @return null|Windows_Azure_Generic_List_Response
+	 * @return null
 	 */
-	protected function _list_items( $prefix, $max_results, $next_marker ) {
+	protected function _list_items( $prefix, $max_results, $next_marker, $path ) {
 		return null;
 	}