Document creating social directory

lib/Client.js

@@ -682,6 +682,11 @@ Client.prototype.getDirectories = function() {
  * creating a directory, you will likely want to map it to an {@link Application} using
  * {@link Application#createAccountStoreMapping Application.createAccountStoreMapping()}.
  *
+ * Directories can be linked to social providers - such as Facebook, Google, Twitter, or
+ * even any other generic OAuth 2.0 provider - by specifing a valid provider containing
+ * the valid `providerId` and client credentials when creating or modifying the directory.
+ * See {@link Provider}.
+ *
  * @param {Object} directory
  * The {@link Directory} resource to create.
  *
@@ -692,13 +697,28 @@ Client.prototype.getDirectories = function() {
  * Callback function, will be called with (err, {@link Directory}).
  *
  * @example
+ * // Creating a simple directory
  * var newDirectory = {
  *   name: 'Customers'
  * }
  *
  * client.createDirectory(newDirectory, function (err, directory) {
  *   console.log(directory);
  * });
+ *
+ * // Creating a social provider directory (e.g. Twitter)
+ * var twitterDirectory = {
+ *   name: 'Twitter Users',
+ *   provider: {
+ *     providerId: 'twitter',
+ *     clientId: 'my-twitter-client-id',
+ *     clientSecret: 'my-twitter-client-secret'
+ *   }
+ * };
+ *
+ * client.createDirectory(twitterDirectory, function (err, directory) {
+ *   console.log(directory);
+ * });
  */
 Client.prototype.createDirectory = function() {
   var args = utils.resolveArgs(arguments, ['dir', 'options', 'callback']);