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

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();

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;