From a7e1318ee8569ff4eb2d807603c38c67ff2e39d3 Mon Sep 17 00:00:00 2001
From: Maciej Sobaczewski <sobak@php.net>
Date: Wed, 23 Nov 2016 21:17:40 +0000
Subject: [PATCH] Document some intl Spoofchecker methods

It also integrates user note 120216

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341114 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/intl/spoofchecker/areconfusable.xml | 41 +++++++++++++------
 reference/intl/spoofchecker/construct.xml     |  9 +---
 reference/intl/spoofchecker/issuspicious.xml  | 30 ++++++++++----
 3 files changed, 53 insertions(+), 27 deletions(-)

diff --git a/reference/intl/spoofchecker/areconfusable.xml b/reference/intl/spoofchecker/areconfusable.xml
index ff267bc24f..fcb139d848 100644
--- a/reference/intl/spoofchecker/areconfusable.xml
+++ b/reference/intl/spoofchecker/areconfusable.xml
@@ -4,41 +4,38 @@
 <refentry xml:id="spoofchecker.areconfusable" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Spoofchecker::areConfusable</refname>
-  <refpurpose>Checks if a given text contains any confusable characters</refpurpose>
+  <refpurpose>Checks if given strings can be confused</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>Spoofchecker::areConfusable</methodname>
-   <methodparam><type>string</type><parameter>s1</parameter></methodparam>
-   <methodparam><type>string</type><parameter>s2</parameter></methodparam>
+   <methodparam><type>string</type><parameter>string1</parameter></methodparam>
+   <methodparam><type>string</type><parameter>string2</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter role="reference">error</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   Checks whether two given strings can easily be mistaken.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
   <variablelist>
    <varlistentry>
-    <term><parameter>s1</parameter></term>
+    <term><parameter>string1</parameter></term>
     <listitem>
      <para>
-      
+      First string to check.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><parameter>s2</parameter></term>
+    <term><parameter>string2</parameter></term>
     <listitem>
      <para>
-      
+      Second string to check.
      </para>
     </listitem>
    </varlistentry>
@@ -46,7 +43,8 @@
     <term><parameter>error</parameter></term>
     <listitem>
      <para>
-      
+      This variable is set by-reference to string containing an error, if there
+      were any.
      </para>
     </listitem>
    </varlistentry>
@@ -56,11 +54,28 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   Returns &true; if two given strings can be confused, &false; otherwise.
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>Spoofchecker::areConfusable</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$checker = new Spoofchecker();
 
+$checker->areConfusable('google.com', 'goog1e.com'); // true: lower l can be confused with digit one
+$checker->areConfusable('google.com', 'g00g1e.com'); // false: zero digit cannot be confused with "o" letter
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/intl/spoofchecker/construct.xml b/reference/intl/spoofchecker/construct.xml
index 25ee0a14c4..b3eba7048e 100644
--- a/reference/intl/spoofchecker/construct.xml
+++ b/reference/intl/spoofchecker/construct.xml
@@ -14,11 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Creates new instance of Spoofchecker.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,11 +26,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   Returns Spoofchecker instance.
   </para>
  </refsect1>
-
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/intl/spoofchecker/issuspicious.xml b/reference/intl/spoofchecker/issuspicious.xml
index 9e2e85f3d2..a91b2ac6e3 100644
--- a/reference/intl/spoofchecker/issuspicious.xml
+++ b/reference/intl/spoofchecker/issuspicious.xml
@@ -15,11 +15,9 @@
    <methodparam choice="opt"><type>string</type><parameter role="reference">error</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   Checks if given string contains any suspicious characters like letters which
+   are almost identical visually, but are Unicode characters from different sets.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +27,7 @@
     <term><parameter>text</parameter></term>
     <listitem>
      <para>
-      
+      String to test.
      </para>
     </listitem>
    </varlistentry>
@@ -37,7 +35,8 @@
     <term><parameter>error</parameter></term>
     <listitem>
      <para>
-      
+      This variable is set by-reference to string containing an error, if there
+      were any.
      </para>
     </listitem>
    </varlistentry>
@@ -47,11 +46,28 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   Returns &true; if there are no suspicious characters, &false; otherwise.
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>Spoofchecker::areConfusable</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$checker = new Spoofchecker();
 
+$checker->isSuspicious('google.com'); // true: only ASCII characters
+$checker->isSuspicious('Рaypal.com'); // false: the first letter is from Cyrylic, not a regular latin "P"
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file