From 6e27fc27fb5697978df43b716f1fe53e64ae6558 Mon Sep 17 00:00:00 2001
From: Kilian Hofmann <llego03@yahoo.com>
Date: Sun, 25 Sep 2022 01:28:37 +0200
Subject: [PATCH] Better PHP Docstring

---
 file/php/Recording.php | 44 ++++++++++++++++++++----------------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/file/php/Recording.php b/file/php/Recording.php
index 6290f76..5614ebd 100644
--- a/file/php/Recording.php
+++ b/file/php/Recording.php
@@ -5,9 +5,7 @@ namespace germanairlinesva_recording;
 class Recording
 {
   private const ident = "VGAR";
-
   private const header_unpack = "Z5ident/Cversion";
-
   private const segment_unpack = "Vtime/Saltitude/Sgroundspeed/elatitude/elongitude";
 
   private string $file_name;
@@ -20,9 +18,9 @@ class Recording
   /**
    * Generates a geoJSON representation
    * 
-   * @return geoJSON representation of path
+   * @return string geoJSON representation of path
    */
-  public function geoJSON()
+  public function geoJSON(): string
   {
     $geoJSON = [
       "type" => "FeatureCollection",
@@ -52,14 +50,14 @@ class Recording
   /**
    * Reads recording
    * 
-   * Array of objects with
-   * @return time Segment time (number)
-   * @return altitude Altitude
-   * @return groundspeed Ground speed
-   * @return latitude Latitude
-   * @return longitude Longitude
+   * @return array Fields:
+   * int Segment time (number) as time,
+   * int Altitude as altitude,
+   * int Ground speed as groundspeed,
+   * double Latitude as latitude,
+   * double Longitude as longitude
    */
-  public function read()
+  public function read(): array
   {
     $file = fopen($this->file_name, "rb");
     flock($file, LOCK_SH);
@@ -85,18 +83,18 @@ class Recording
    * 
    * @param resource $file File handle
    * 
-   * If not EOF
-   * @return time Segment time (number)
-   * @return altitude Altitude
-   * @return groundspeed Ground speed
-   * @return latitude Latitude
-   * @return longitude Longitude
-   * Else
-   * @return false
+   * @return array if not EOF with fields:
+   * int Segment time (number) as time,
+   * int Altitude as altitude,
+   * int Ground speed as groundspeed,
+   * double Latitude as latitude,
+   * double Longitude as longitude 
+   * 
+   * @return false if EOF
    * 
    * @throws InvalidArgumentException If file is not a resource
    */
-  private function read_segment_1($file)
+  private function read_segment_1($file): array | false
   {
     if (false === is_resource($file)) {
       throw new \InvalidArgumentException(sprintf('Argument must be a valid resource type. %s given.', gettype($file)));
@@ -111,14 +109,14 @@ class Recording
   /**
    * Reads the file header
    * 
-   * @param resource file File handle
+   * @param resource $file File handle
    * 
-   * @return version File version
+   * @return string File version
    * 
    * @throws InvalidArgumentException If file is not a resource
    * @throws UnexpectedValueException If ident mismatches
    */
-  private function read_header($file)
+  private function read_header($file): string
   {
     if (false === is_resource($file)) {
       throw new \InvalidArgumentException(sprintf('Argument must be a valid resource type. %s given.', gettype($file)));