- Fixed bug #39805: Make these docs less vague.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@224894 c90b9560-bf6c-de11-be94-00142212c4b1

reference/datetime/functions/timezone-offset-get.xml

@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id="function.timezone-offset-get">
  <refnamediv>
   <refname>timezone_offset_get</refname>
-  <refpurpose>Returns the timezone offset</refpurpose>
+  <refpurpose>Returns the timezone offset from GMT</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -16,6 +16,11 @@
    <type>int</type><methodname>DateTimeZone::getOffset</methodname>
    <methodparam><type>DateTime</type><parameter>datetime</parameter></methodparam>
   </methodsynopsis>
+  <para>
+   This function returns the offset to GMT for the date/time specified in the
+   <parameter>datetime</parameter> parameter. The GMT offset is calculated
+   with the timezone information contained in the DateTime object being used.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -34,7 +39,7 @@
      <term><parameter>datetime</parameter></term>
      <listitem>
       <para>
-       DateTime to compute offset from.
+       DateTime that contains the date/time to compute the offset from. 
       </para>
      </listitem>
     </varlistentry>
@@ -49,6 +54,38 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>date</function> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Create two timezone objects, one for Taipei (Taiwan) and one for
+// Tokyo (Japan)
+$dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
+$dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");
+
+// Create two DateTime objects that will contain the same Unix timestamp, but
+// have different timezones attached to them.
+$dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
+$dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);
+
+// Calculate the GMT offset for the date/time contained in the $dateTimeTaipei
+// object, but using the timezone rules as defined for Tokyo
+// ($dateTimeZoneJapan).
+$timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);
+
+// Should show int(32400) (for dates after Sat Sep 8 01:00:00 1951 JST).
+var_dump($timeOffset);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file