doc: Updates to documentation and consistency formatting for stubs

Author: mikefero

CHANGELOG.md

@@ -2,13 +2,14 @@
 
 Features:
 
-* Persistent Sessions (can be disabled via `Cassandra\Cluster\Builder::withPersistentSessions()`).
+* Persistent sessions (can be disabled via `Cassandra\Cluster\Builder::withPersistentSessions()`).
 * Windows support.
 * Configurable log location (via `cassandra.log` ini setting).
 * Configurable log level (via `cassandra.log_level` ini setting).
-* Upgraded to CPP driver v2.0.
+* Upgraded to C/C++ driver v2.0.
 * Added math functions to numeric types and `Cassandra\Numeric` interface.
 * All classes moved into the extension.
+* Added stub files for IDEs.
 
 Bug Fixes:
 

CONTRIBUTING.md

@@ -7,6 +7,7 @@ help the maintainer to fix the bug that you've discovered quicker:
 
 * [Use the PHP Driver Jira](https://datastax-oss.atlassian.net/projects/PHP) to report all issues and bugs.
 * Include the version of the Driver, PHP and Cassandra or DSE in your Jira ticket.
+ * Include the Driver dependency versions as well (e.g. libuv, C/C++ Driver, ...etc)
 * Include a complete stack trace of the failure as well as any available logs.
 * Include any additional information you think is relevant - the description of
   your setup, any non-default Driver configuration, etc.

README.md

@@ -22,15 +22,18 @@ upcoming releases.
 
 ## What's new in v1.0.0.beta:
 
-* Persistent Sessions.
+* Persistent sessions.
 * Windows support.
+* Configurable logger (file/syslog and level).
 * Math functions for numeric types and `Cassandra\Numeric` interface.
 * All classes moved into the extension.
+* Upgraded to use the C/C++ driver v2.0.
+* Added stub files for IDEs.
 
 ## Planned
 
 * Ability to configure connection pooling.
-* Ability to configure latency aware load balancing
+* Ability to configure latency aware load balancing.
 * Expose [Schema Metadata](http://datastax.github.io/cpp-driver/api/struct_cass_session/#1afc51badec695483e4cde43ae0fc1e876).
 
 ## Quick Start
@@ -64,10 +67,9 @@ Cassandra's native protocol. The current version works with:
 * Apache Cassandra versions 1.2, 2.0 and partially 2.1
 * DataStax Enterprise 3.1, 3.2, 4.0 and 4.5
 * PHP 5.3+
+* Compilers: GCC 4.1.2+, Clang 3.4+, and MSVC 2010/2012/2013
 
-__NOTE__: Apache Cassandra 2.1 support is limited to the Cassandra 2.0 API, e.g. no user-defined types.
-
-__NOTE__: Windows support is planned for a later, more stable release.
+__NOTE__: Apache Cassandra 2.1 support is limited to the Cassandra 2.0 API (native protocol v2), e.g. no user-defined types.
 
 ## Contributing
 
@@ -93,13 +95,14 @@ vagrant up
 vagrant ssh
 ```
 
-Once you've logged in to the vagrant vm, run:
+Once you've logged in to the vagrant VM, run:
 
 ```bash
 cd /usr/local/src/php-driver
 ./bin/behat
 ./bin/phpunit
 ```
+
 ## Copyright
 
 Copyright 2015 DataStax, Inc.

ext/doc/Cassandra/Bigint.php

@@ -24,19 +24,22 @@
 final class Bigint implements Numeric
 {
     /**
-     * Creates a new 64bit integer
+     * Creates a new 64bit integer.
+     *
      * @param string $value integer value as a string
      */
     public function __construct($value) {}
 
     /**
-     * Returns the integer value
+     * Returns the integer value.
+     *
      * @return string integer value
      */
     public function value() {}
 
     /**
-     * Returns string representation of the integer value
+     * Returns string representation of the integer value.
+     *
      * @return string integer value
      */
     public function __toString() {}

ext/doc/Cassandra/Blob.php

@@ -24,19 +24,22 @@
 final class Blob
 {
     /**
-     * Creates a new bytes array
+     * Creates a new bytes array.
+     *
      * @param string $bytes any bytes
      */
     public function __construct($bytes) {}
 
     /**
-     * Returns bytes as a hex string
+     * Returns bytes as a hex string.
+     *
      * @return string bytes as hexadecimal string
      */
     public function bytes() {}
 
     /**
-     * Returns bytes as a hex string
+     * Returns bytes as a hex string.
+     *
      * @return string bytes as hexadecimal string
      */
     public function __toString() {}

ext/doc/Cassandra/Cluster/Builder.php

@@ -74,6 +74,8 @@ public function withContactPoints($host) {}
     /**
      * Specify a different port to be used when connecting to the cluster.
      *
+     * @throws Cassandra\Exception\InvalidArgumentException
+     *
      * @param int $port a number between 1 and 65535
      *
      * @return Builder self
@@ -101,7 +103,7 @@ public function withDatacenterAwareRoundRobinLoadBalancingPolicy($localDatacente
     /**
      * Enable token aware routing.
      *
-     * @param bool $enabled Whether to enable token aware routing
+     * @param bool $enabled Whether to enable token aware routing (optional)
      *
      * @return Builder self
      */
@@ -144,9 +146,10 @@ public function withRequestTimeout($timeout) {}
     public function withSSL(SSLOptions $options) {}
 
     /**
-     * Enable persistent sessions and clusters
+     * Enable persistent sessions and clusters.
      *
-     * @param bool $enabled whether to enable persistent sessions and clusters.
+     * @param bool $enabled whether to enable persistent sessions and clusters
+     *                      (optional)
      *
      * @return Builder self
      */

ext/doc/Cassandra/Collection.php

@@ -24,40 +24,49 @@
 final class Collection implements \Countable, \IteratorAggregate
 {
     /**
-     * Creates a new collection of a given type
+     * Creates a new collection of a given type.
+     *
      * @param string $type one of `Cassandra::TYPE_*`
      */
     public function __construct($type) {}
 
     /**
-     * The type of this collection
+     * The type of this collection.
+     *
      * @return string one of `Cassandra::TYPE_*`
      */
     public function type() {}
 
     /**
-     * Array of values in this collection
+     * Array of values in this collection.
+     *
      * @return array values
      */
     public function values() {}
 
     /**
-     * Adds one or more values to this collection
+     * Adds one or more values to this collection.
+     *
      * @param mixed $value,... one or more values to add
+     *
      * @return int total number of values in this collection
      */
     public function add($value) {}
 
     /**
-     * Retrieves the value at a given index
+     * Retrieves the value at a given index.
+     *
      * @param   int         $index  Index
+     *
      * @return  mixed|null          Value
      */
     public function get($index) {}
 
     /**
-     * Finds index of a value in this collection
+     * Finds index of a value in this collection.
+     *
      * @param   mixed     $value Value
+     *
      * @return  int|null         Index
      */
     public function find($value) {}

ext/doc/Cassandra/Decimal.php

@@ -36,25 +36,27 @@ final class Decimal implements Numeric
      * $this->assertEquals("1313123123234234234234234234123", $decimal->value());
      * ~~~
      *
-     *
      * @param string $value Any decimal string
      */
     public function __construct($value) {}
 
     /**
-     * String representation of this decimal
+     * String representation of this decimal.
+     *
      * @return string Decimal value
      */
     public function __toString() {}
 
     /**
-     * Numeric value of this decimal as string
+     * Numeric value of this decimal as string.
+     *
      * @return string Numeric value
      */
     public function value() {}
 
     /**
-     * Scale of this decimal as int
+     * Scale of this decimal as int.
+     *
      * @return int Scale
      */
     public function scale() {}

ext/doc/Cassandra/Exception/DomainException.php

@@ -21,6 +21,6 @@
 use Cassandra\Exception;
 
 /**
- * Cassandra-specific domain exception
+ * Cassandra-specific domain exception.
  */
 class DomainException extends \DomainException implements Exception {}

ext/doc/Cassandra/Exception/InvalidArgumentException.php

@@ -21,6 +21,6 @@
 use Cassandra\Exception;
 
 /**
- * Cassandra-specific invalid argument exception
+ * Cassandra-specific invalid argument exception.
  */
 class InvalidArgumentException extends \InvalidArgumentException implements Exception {}

ext/doc/Cassandra/Exception/LogicException.php

@@ -21,6 +21,6 @@
 use Cassandra\Exception;
 
 /**
- * Cassandra-specific logic exception
+ * Cassandra-specific logic exception.
  */
 class LogicException extends \LogicException implements Exception {}

ext/doc/Cassandra/Exception/ReadTimeoutException.php

@@ -19,8 +19,8 @@
 namespace Cassandra\Exception;
 
 /**
- * ReadTimeoutException is raised when coordinator failed to receive acks from
- * the required number of replica nodes in time during a read.
+ * ReadTimeoutException is raised when a coordinator failed to receive acks
+ * from the required number of replica nodes in time during a read.
  * @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L709-L726 Description of ReadTimeout error in the native protocol spec
  */
 class ReadTimeoutException extends ExecutionException {}

ext/doc/Cassandra/Exception/RuntimeException.php

@@ -21,6 +21,6 @@
 use Cassandra\Exception;
 
 /**
- * Cassandra-specific runtime exception
+ * Cassandra-specific runtime exception.
  */
 class RuntimeException extends \RuntimeException implements Exception {}

ext/doc/Cassandra/Exception/ServerException.php

@@ -19,7 +19,7 @@
 namespace Cassandra\Exception;
 
 /**
- * Server exception is raised when something unexpected happend on the server.
+ * ServerException is raised when something unexpected happend on the server.
  * This exception is most likely due to an Apache Cassandra bug.
  * **NOTE** This exception and all its children are generated on the server.
  */

ext/doc/Cassandra/Exception/TimeoutException.php

@@ -19,7 +19,7 @@
 namespace Cassandra\Exception;
 
 /**
- * Timeout exception, this is generally raised with future did not resolved
+ * TimeoutException is generally raised when a future did not resolve
  * within a given time interval.
  */
 class TimeoutException extends RuntimeException {}

ext/doc/Cassandra/Exception/TruncateException.php

@@ -19,6 +19,7 @@
 namespace Cassandra\Exception;
 
 /**
- * TruncateException is raised when something went wrong during table truncation.
+ * TruncateException is raised when something went wrong during table
+ * truncation.
  */
 class TruncateException extends ExecutionException {}

ext/doc/Cassandra/Exception/UnavailableException.php

@@ -19,9 +19,10 @@
 namespace Cassandra\Exception;
 
 /**
- * UnavailableException is raised when coordinator detected that there aren't
- * enough replica nodes available to fulfill the request. Request has not even
- * been forwarded to the replica nodes in this case.
+ * UnavailableException is raised when a coordinator detected that there aren't
+ * enough replica nodes available to fulfill the request.
+ *
+ * NOTE: Request has not even been forwarded to the replica nodes in this case.
  * @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L667-L677 Description of the Unavailable error in the native protocol v1 spec.
  */
 class UnavailableException extends ExecutionException {}

ext/doc/Cassandra/Exception/WriteTimeout.php

@@ -19,8 +19,8 @@
 namespace Cassandra\Exception;
 
 /**
- * WriteTimeoutException is raised when coordinator failed to receive acks from
- * the required number of replica nodes in time during a write.
+ * WriteTimeoutException is raised when a coordinator failed to receive acks
+ * from the required number of replica nodes in time during a write.
  * @see https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v1.spec#L683-L708 Description of WriteTimeout error in the native protocol spec
  */
 class WriteTimeoutException extends ExecutionException {}

ext/doc/Cassandra/ExecutionOptions.php

@@ -29,6 +29,8 @@
 final class ExecutionOptions
 {
     /**
+     * Creates a new options object for execution.
+     *
      * @throws Cassandra\Exception\InvalidArgumentException
      *
      * array['arguments']          array    An array or positional or named arguments

ext/doc/Cassandra/Float.php

@@ -24,19 +24,22 @@
 final class Float implements Numeric
 {
     /**
-     * Creates a new float
+     * Creates a new float.
+     *
      * @param string $value float value as a string
      */
     public function __construct($value) {}
 
     /**
-     * Returns the float value
+     * Returns the float value.
+     *
      * @return string float value
      */
     public function value() {}
 
     /**
-     * Returns string representation of the float value
+     * Returns string representation of the float value.
+     *
      * @return string float value
      */
     public function __toString() {}