From 6250f7fb10444fccf321d770d8b62f9adc7cb935 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sun, 11 Feb 2018 16:41:08 +0000
Subject: [PATCH] Clarify possible element types

We also give examples for polar night and midnight sun.
This integrates user note 83903 and 116828.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@344216 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../datetime/functions/date-sun-info.xml      | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/reference/datetime/functions/date-sun-info.xml b/reference/datetime/functions/date-sun-info.xml
index 39892eec90..f3234dbefc 100644
--- a/reference/datetime/functions/date-sun-info.xml
+++ b/reference/datetime/functions/date-sun-info.xml
@@ -51,6 +51,9 @@
   &reftitle.returnvalues;
   <para>
    Returns array on success&return.falseforfailure;.
+   The values of the array elements are either UNIX timestamps, &false; if the
+   sun is below the respective zenith for the whole day, or &true; if the sun is
+   above the respective zenith for the whole day.
   </para>
  </refsect1>
 
@@ -104,6 +107,76 @@ nautical_twilight_begin: 04:52:25
 nautical_twilight_end: 16:41:06
 astronomical_twilight_begin: 04:21:32
 astronomical_twilight_end: 17:12:00
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Polar night</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(date_sun_info(strtotime("2017-12-21"), 90, 0));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+array(9) {
+  ["sunrise"]=>
+  bool(false)
+  ["sunset"]=>
+  bool(false)
+  ["transit"]=>
+  int(1513857490)
+  ["civil_twilight_begin"]=>
+  bool(false)
+  ["civil_twilight_end"]=>
+  bool(false)
+  ["nautical_twilight_begin"]=>
+  bool(false)
+  ["nautical_twilight_end"]=>
+  bool(false)
+  ["astronomical_twilight_begin"]=>
+  bool(false)
+  ["astronomical_twilight_end"]=>
+  bool(false)
+}
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Midnight sun</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(date_sun_info(strtotime("2017-06-21"), 90, 0));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+array(9) {
+  ["sunrise"]=>
+  bool(true)
+  ["sunset"]=>
+  bool(true)
+  ["transit"]=>
+  int(1498046510)
+  ["civil_twilight_begin"]=>
+  bool(true)
+  ["civil_twilight_end"]=>
+  bool(true)
+  ["nautical_twilight_begin"]=>
+  bool(true)
+  ["nautical_twilight_end"]=>
+  bool(true)
+  ["astronomical_twilight_begin"]=>
+  bool(true)
+  ["astronomical_twilight_end"]=>
+  bool(true)
+}
 ]]>
     </screen>
    </example>