From 9f07e5083dfa523c81126c0edf67a3360906b74a Mon Sep 17 00:00:00 2001
From: Andre Klapper <a9016009@gmx.de>
Date: Tue, 20 Aug 2024 13:05:49 +0200
Subject: [PATCH] Add some DateTime handling related PHPDocs

Summary:
As I was fiddling with an exception handling invalid DateTime, add some PHPDoc
for the next time someone needs to understand this code.

Test Plan: Use `get_class()` to check parameters and return values.

Reviewers: O1 Blessed Committers, valerio.bozzolan

Reviewed By: O1 Blessed Committers, valerio.bozzolan

Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Differential Revision: https://we.phorge.it/D25793
---
 .../query/PhabricatorCalendarEventSearchEngine.php   |  4 ++++
 .../form/control/AphrontFormDateControlValue.php     | 12 ++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php b/src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php
index 3a6e931515..d553177e4f 100644
--- a/src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php
+++ b/src/applications/calendar/query/PhabricatorCalendarEventSearchEngine.php
@@ -525,6 +525,10 @@ final class PhabricatorCalendarEventSearchEngine
     }
   }
 
+  /**
+   * @param PhabricatorSavedQuery $saved
+   * @return AphrontFormDateControlValue
+   */
   private function getQueryDateFrom(PhabricatorSavedQuery $saved) {
     if ($this->calendarYear && $this->calendarMonth) {
       $viewer = $this->requireViewer();
diff --git a/src/view/form/control/AphrontFormDateControlValue.php b/src/view/form/control/AphrontFormDateControlValue.php
index b4d3e08a0b..72221dd287 100644
--- a/src/view/form/control/AphrontFormDateControlValue.php
+++ b/src/view/form/control/AphrontFormDateControlValue.php
@@ -209,6 +209,12 @@ final class AphrontFormDateControlValue extends Phobject {
     );
   }
 
+  /**
+   * Create a DateTime object including timezone
+   * @param string $date Date, like "2024-08-20" or "2024-07-1" or such
+   * @param string|null $time Time, like "12:00 AM" or such
+   * @return DateTime|null
+   */
   private function newDateTime($date, $time) {
     $date = $this->getStandardDateFormat($date);
     $time = $this->getStandardTimeFormat($time);
@@ -280,10 +286,16 @@ final class AphrontFormDateControlValue extends Phobject {
     }
   }
 
+  /**
+   * @return DateTime|null
+   */
   public function getDateTime() {
     return $this->newDateTime($this->valueDate, $this->valueTime);
   }
 
+  /**
+   * @return DateTimeZone
+   */
   private function getTimezone() {
     if ($this->zone) {
       return $this->zone;