From fce4cad98c8b1b812dacdf439b07f34f4f76764a Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Thu, 19 Jul 2012 14:45:48 +0000
Subject: [PATCH] Document MongoCursorException->getHost() &
 MongoCollection->distinct()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@326701 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongocollection/distinct.xml  | 156 ++++++++++++++++++
 reference/mongo/mongocursorexception.xml      |   2 +
 .../mongo/mongocursorexception/gethost.xml    |  56 +++++++
 reference/mongo/versions.xml                  |   1 +
 4 files changed, 215 insertions(+)
 create mode 100644 reference/mongo/mongocollection/distinct.xml
 create mode 100644 reference/mongo/mongocursorexception/gethost.xml

diff --git a/reference/mongo/mongocollection/distinct.xml b/reference/mongo/mongocollection/distinct.xml
new file mode 100644
index 0000000000..053e8c3638
--- /dev/null
+++ b/reference/mongo/mongocollection/distinct.xml
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="mongocollection.distinct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoCollection::distinct</refname>
+  <refpurpose>Retrieve a list of distinct values for the given key across a collection.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>array</type><methodname>MongoCollection::distinct</methodname>
+   <methodparam><type>string</type><parameter>key</parameter></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>query</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   The distinct command returns a list of distinct values for the given key
+   across a collection. 
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>key</parameter></term>
+    <listitem>
+     <para>
+      The key to use.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>query</parameter></term>
+    <listitem>
+     <para>
+      An optional query parameters 
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an array of distinct values, &return.falseforfailure;
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="mongocollection.distinct.basic">
+   <title><methodname>MongoCollection::distinct</methodname> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new Mongo;
+$db = $m->selectDB("test");
+$db->dropCollection("distinct");
+$c = $db->distinct;
+
+$c->insert(array("stuff" => "bar", "zip-code" => 10010));
+$c->insert(array("stuff" => "foo", "zip-code" => 10010));
+$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("safe" => true));
+
+$retval = $c->distinct("zip-code");
+var_dump($retval);
+
+$retval = $c->distinct("zip-code", array("stuff" => "foo"));
+var_dump($retval);
+
+$retval = $c->distinct("zip-code", array("stuff" => "bar"));
+var_dump($retval);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+array(2) {
+  [0]=>
+  int(10010)
+  [1]=>
+  int(99701)
+}
+array(1) {
+  [0]=>
+  int(10010)
+}
+array(2) {
+  [0]=>
+  int(10010)
+  [1]=>
+  int(99701)
+}
+]]>
+   </screen>
+  </example>
+  <example xml:id="mongocollection.distinct.basic-embedded">
+   <title><methodname>MongoCollection::distinct</methodname> example on a embedded document</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$c->insert(array("user" => array("points" => 25)));
+$c->insert(array("user" => array("points" => 31)));
+$c->insert(array("user" => array("points" => 25)), array("safe" => true));
+
+$retval = $c->distinct("user.points");
+var_dump($retval);
+
+$retval = $c->distinct("user.nonexisting");
+var_dump($retval);
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+array(2) {
+  [0]=>
+  int(25)
+  [1]=>
+  int(31)
+}
+array(0) {
+}
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml
index a32e41408b..e508c3158e 100644
--- a/reference/mongo/mongocursorexception.xml
+++ b/reference/mongo/mongocursorexception.xml
@@ -406,6 +406,8 @@ catch (MongoCursorException $e) {
 
  </partintro>
 
+ &reference.mongo.entities.mongocursorexception;
+
 </phpdoc:classref>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mongo/mongocursorexception/gethost.xml b/reference/mongo/mongocursorexception/gethost.xml
new file mode 100644
index 0000000000..6b58b3e4ea
--- /dev/null
+++ b/reference/mongo/mongocursorexception/gethost.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="mongocursorexception.gethost" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoCursorException::getHost</refname>
+  <refpurpose>The hostname of the server that encountered the error</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>string</type><methodname>MongoCursorException::getHost</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+  Returns the hostname of the server the query was sent too.
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the hostname, or <type>NULL</type> if the hostname is unknown.
+  </para>
+ </refsect1>
+
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongo/versions.xml b/reference/mongo/versions.xml
index 5a78e3b67a..059a32b9e3 100644
--- a/reference/mongo/versions.xml
+++ b/reference/mongo/versions.xml
@@ -70,6 +70,7 @@
  <function name='mongocollection::createdbref' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocollection::getdbref' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocollection::group' from='PECL mongo &gt;=0.9.2'/>
+ <function name='mongocollection::distinct' from='PECL mongo &gt;=1.2.11'/>
  <function name='mongocollection::setslaveokay' from='PECL mongo &gt;=1.1.0'/>
  <function name='mongocollection::getslaveokay' from='PECL mongo &gt;=1.1.0'/>
  <!-- MongoCursor -->