Merge branch 'master' into doc_and_stub_updates

Conflicts:
	README.md

Author: mikefero

.clang-format

@@ -0,0 +1,40 @@
+BasedOnStyle: LLVM
+AlignAfterOpenBracket: true
+AlignConsecutiveAssignments: true
+AlignEscapedNewlinesLeft: true
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: true
+AlwaysBreakBeforeMultilineStrings: true
+BinPackArguments: true
+BinPackParameters: false
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeBraces: Linux
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializersBeforeComma: true
+ColumnLimit: 0
+ContinuationIndentWidth: 2
+Cpp11BracedListStyle: false
+DerivePointerAlignment: false
+IndentCaseLabels: false
+IndentWidth: 2
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: false
+MaxEmptyLinesToKeep: 1
+PointerAlignment: Left
+SpaceAfterCStyleCast: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+TabWidth: 2
+UseTab: Never

CONTRIBUTING.md

@@ -14,8 +14,24 @@ help the maintainer to fix the bug that you've discovered quicker:
 * Write a failing test. The PHP Driver uses [PHPUnit test framework](https://phpunit.de/). A reliably
   failing test is the fastest way to demonstrate and fix a problem.
 
-## Pull Requests
+## Pull requests
 
 If you're able to fix a bug yourself, you can [fork the repository](https://help.github.com/articles/fork-a-repo/) and [submit a pull request](https://help.github.com/articles/using-pull-requests/) with the fix.
 
 To protect DataStax and the community, all contributors are required to [sign the DataStax Contribution License Agreement](http://cla.datastax.com/). The process is completely electronic and should only take a few minutes.
+
+## Style guide
+
+There are 2 distinct coding styles used in the repository. Depending on which part of the codebase you're going to touch, you need to follow one or the other.
+
+### PHP coding style
+
+The API stubs provided by the extension are following [the Symfony 2 coding standard](http://symfony.com/doc/current/contributing/code/standards.html). The only exception are empty method stubs, those have opening and closing brace following the closing parenthesis on the same line.
+
+### C coding style
+
+The main difference here is the spacing, the C code uses 2 spaces for indendation, while the PHP code - 4. For your convenience, a `.clang-format` file is available in the repository's root directory. Using `clang-format`, you can format source files to match the coding style almost completely:
+
+```bash
+clang-format -style=file -i ext/php_cassandra.c
+```

README.md

@@ -22,10 +22,10 @@ upcoming releases.
 
 ## What's new in v1.0.0.beta:
 
-* Persistent sessions.
+* [Persistent sessions](http://datastax.github.io/php-driver/features/#persistent-sessions).
 * Windows support.
 * Configurable logger (file/syslog and level).
-* Math functions for numeric types and `Cassandra\Numeric` interface.
+* Math functions for numeric types and [`Cassandra\Numeric`](http://datastax.github.io/php-driver/api/interface/Cassandra/Numeric/) interface.
 * All classes moved into the extension.
 * Upgraded to use the C/C++ driver v2.0.
 * Added stub files for IDEs.
@@ -79,8 +79,8 @@ __NOTE__: Apache Cassandra 2.1 support is limited to the Cassandra 2.0 API (nati
 
 The DataStax PHP Driver uses the amazing [Behat Framework](http://docs.behat.org/)
 for both end-to-end, or acceptance, testing and documentation. All of the features
-supported by the driver have appropriate acceptance tests with easy-to-copy code
-examples in the `features/` directory.
+supported by the driver have appropriate acceptance tests with [easy-to-copy code
+examples in the `features/` directory](https://github.com/datastax/php-driver/tree/master/features).
 
 ## Running tests
 

features/README.md

@@ -4,9 +4,9 @@
 
 ### Specifying addresses of Cassandra nodes
 
-[`withContactPoints()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-contact-points) and [`withPort()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-port) methods of the [`Cassandra\Cluster\Builder`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/) are used to specify ip addresses or hostnames and port number of the nodes in a given Cassandra cluster.
+[`withContactPoints()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-contact-points) and [`withPort()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-port) methods of the [`Cassandra\Cluster\Builder`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/) are used to specify IP addresses or hostnames and port number of the nodes in a given Cassandra cluster.
 
-Note that you don't have to specify the addresses of all hosts in your cluster. Once the driver has established a connection to any host, it will perform auto-discovery of and connect to all hosts in the cluster.
+Note that you don't have to specify the addresses of all hosts in your cluster. Once the driver has established a connection to any host, it will perform auto-discovery and connect to all hosts in the cluster.
 
 ```php
 <?php
@@ -20,7 +20,7 @@ $session = $cluster->connect();
 
 ### Discovering nodes in the cluster
 
-After the initial connection to one of the hosts specified via `withContactPoints()` succeeded, the driver discovers the addresses and connects to all members of the cluster automatically. You can also see the nodes that the driver discovered by running `SELECT * FROM system.peers`.
+After the initial connection to one of the hosts specified via `withContactPoints()` succeeds, the driver discovers the addresses and connects to all members of the cluster automatically. You can also see the nodes that the driver discovered by running `SELECT * FROM system.peers`.
 
 ### Persistent sessions
 
@@ -43,9 +43,9 @@ Persistent sessions stay alive for the duration of the parent process, typically
 
 ### Configuring load balancing policy
 
-PHP Driver comes with a variety of load balancing policies. By default it uses a combination of token aware data center round robin.
+The PHP Driver comes with a variety of load balancing policies. By default it uses a combination of token aware data center round robin.
 
-The token aware load balancing policy uses the same hashing algorithms as the Apache Cassandra to route prepared statements execution directly to replica nodes, avoiding an additional network hop to/from the coordinator. You can toggle its usage with [`Cassandra\Cluster\Builder::withTokenAwareRouting()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-token-aware-routing).
+The token aware load balancing policy uses the same hashing algorithms as the Apache Cassandra to directly route the execution of prepared statements to the replica node, avoiding an additional network hop to/from the coordinator. You can toggle its usage with [`Cassandra\Cluster\Builder::withTokenAwareRouting()`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-token-aware-routing).
 
 ```php
 <?php
@@ -141,9 +141,9 @@ $session->execute(
 
 For frequently executed queries, it's strongly recommended to use prepared statements. As a rule of thumb, if your application is sending a request more than once, a prepared statement is almost always the right choice.
 
-### Prepared Statements
+### Prepared statements
 
-The driver supports prepared statements. Use [`Cassandra\Session::prepare()`](http://datastax.github.io/php-driver/api/interface/Cassandra/Session/#prepare) to create a [`Cassandra\PreparedStatement` object](http://datastax.github.io/php-driver/api/class/Cassandra/PreparedStatement/), and then call [`Cassandra\Session::execute()`](http://datastax.github.io/php-driver/api/interface/Cassandra/Session/#execute).
+The driver supports prepared statements. Use [`Cassandra\Session::prepare()`](http://datastax.github.io/php-driver/api/interface/Cassandra/Session/#prepare) to create a [`Cassandra\PreparedStatement`](http://datastax.github.io/php-driver/api/class/Cassandra/PreparedStatement/) object, and then call [`Cassandra\Session::execute()`](http://datastax.github.io/php-driver/api/interface/Cassandra/Session/#execute).
 
 ```php
 <?php
@@ -159,7 +159,7 @@ A prepared statement can be run many times, but the CQL parsing will only be don
 
 ### Executing statements in parallel
 
-With fully asynchronous api, it is very easy to run queries in parallel:
+With fully asynchronous API, it is very easy to run queries in parallel:
 
 ```php
 <?php
@@ -347,7 +347,9 @@ cassandra.log=syslog
 cassandra.log_level=INFO
 ```
 
-You can specify any file path as `cassandra.log`. The special value `syslog` can be used to for the driver to use syslog for logging.
+You can specify any file path as `cassandra.log`.
+
+The special value `syslog` can be used to for the driver to use syslog for logging. Syslog is only supported on \*nix systems.
 
 The possible log levels are:
 
@@ -364,6 +366,6 @@ Most of the logging will be when the driver connects and discovers new nodes, wh
 
 The PHP Driver follows the architecture of [the C/C++ Driver](http://datastax.github.io/cpp-driver/topics/#architecture) that it wraps.
 
-### Persistent Sessions
+### Persistent sessions
 
 By default, the driver uses persistent sessions to prevent each request from creating completely new TCP connections to a Cassandra cluster. You can toggle this functionality using [`Cassandra\Cluster\Builder::withPersistentSessions`](http://datastax.github.io/php-driver/api/class/Cassandra/Cluster/Builder/#with-persistent-sessions)