* Little apigen documentation

Author: mrblur

.gitignore

@@ -1,2 +1,3 @@
 /nbproject/private/
-/view/analytics.html
+/view/analytics.html
+/doc/

apigen.neon

@@ -0,0 +1,5 @@
+source:
+    - lib
+
+destination: doc
+templateTheme: bootstrap

lib/fuelioimporter/cost.class.php

@@ -53,12 +53,12 @@ public function setCost($dCost)
 
     public function setFlag($flag)
     {
-        $this->flag = $flag; // TODO: What is "flag"? 
+        $this->flag = $flag; // @TODO: What is "flag"? 
     }
 
     public function setIdR($iId)
     {
-        $this->idR = $iId; // TODO: What is Id R? Isn't it "internal"
+        $this->idR = $iId; // @TODO: What is Id R? Isn't it "internal"
     }
 
     public function setRead($bRead)

lib/fuelioimporter/fuellogentry.class.php

@@ -50,7 +50,7 @@ public function setGeoCoords($dLatitude, $dLongitude) {
         $this->longitude = $dLongitude;
 
         // Fuelio requires city name to display geo data on map
-        if (empty($this->city))
+        if (!empty($dLatitude) && empty($this->city))
         {
             $this->setCity('GPS');
         }

lib/fuelioimporter/ibackupentry.class.php

@@ -2,7 +2,14 @@
 
 namespace FuelioImporter;
 
+/**
+ * Interface for generic Fuelio file entries
+ * @author Kamil Kamiński
+ */
 interface IBackupEntry {
-    // Returns fputcsv array
+    /**
+     * Returns array for fputcsv
+     * @return array
+     */
     public function getData();
 }

lib/fuelioimporter/iconverter.class.php

@@ -1,23 +1,59 @@
 <?php
 
 namespace FuelioImporter;
-use SplFileObject;
+use \SplFileObject;
 
+/**
+ * Interface for converters
+ * @author Kamil Kamiński
+ */
 interface IConverter {
-    // Internal name of converter (as in hashtags)
+    /**
+     * Internal name of converter (as in hashtags)
+     * @return string
+     */
     public function getName();
-    // Full name of converter
+    
+    /**
+     * Full name of converter
+     * @return string
+     */
     public function getTitle();
-    // Array of errors during conversion
+    
+    /**
+     * Array of errors during conversion
+     * @return array
+     */
     public function getErrors();
-    // Array of warnings
+    
+    /**
+     * Array of warnings
+     * @return array()
+     */
     public function getWarnings();
-    // Method that processes given file returning SplTempFileObject
+    
+    /**
+     * Method that processes given file returning SplTempFileObject
+     * @return FuelioImporter\FuelioBackupBuilder
+     */
     public function processFile(SplFileObject $stream);
-    // Method returns a CardInterface for visual representation
+    
+    /**
+     * Method returns a CardInterface for visual representation
+     * @return ICard
+     */
     public function getCard();
-    // Optional stylesheet to include on page
+    
+    /**
+     * Optional stylesheet to include on page
+     * @return string|null
+     */
     public function getStylesheetLocation();
-    // Sets car name
+    
+    /**
+     * Sets car name
+     * 
+     * @param string $name Car name
+     */
     public function setCarName($name);
 }

lib/fuelioimporter/providers/acarcard.class.php

@@ -18,7 +18,7 @@ public function getMenu() {
     }
 
     public function getActions() {
-        // todo: One day maybe we will use a proper class
+        // @todo: One day maybe we will use a proper class
         return array(
             array('Help', 'popup', 'acarhelp.html')
         );

lib/fuelioimporter/providers/acarprovider.class.php

@@ -190,7 +190,7 @@ public function processVehicle(SimpleXMLElement $data, ZipArchive $in, FuelioBac
      * @throws \FuelioImporter\InvalidUnitException On unsupported unit
      */
     protected function getFuelUnit() {
-        // TODO: How does aCar mark US / UK gallons?
+        // @TODO: How does aCar mark US / UK gallons?
         switch ($this->preferences['acar.volume-unit']) {
             case 'L':
                 return Vehicle::LITRES;
@@ -222,7 +222,7 @@ protected function getDistanceUnit() {
      * @throws \FuelioImporter\InvalidUnitException
      */
     protected function getConsumptionUnit() {
-        // TODO: check the format behind other options:
+        // @TODO: check the format behind other options:
         // mpg (us), mpg (imperial), gal/100mi (us), gal/100mi (imperial), km/L, km/gal (us), km/gal (imperial). mi/L
         switch ($this->preferences['acar.fuel-efficiency-unit']) {
 

lib/fuelioimporter/vehicle.class.php

@@ -4,38 +4,82 @@
 
 use FuelioImporter\IBackupEntry;
 
+/**
+ * Fuelio Vehicle data
+ * @author Kamil Kamiński
+ * @version 20150727
+ */
 class Vehicle implements IBackupEntry {
 
-    // Distance units
+    /** Distance unit */
     const KILOMETERS = 0;
+    /** Distance unit */
     const MILES = 1;
 
-    // Fuel units
+    /** Fuel unit */
     const LITRES = 0;
+    /** Fuel unit */
     const GALLONS_US = 1;
+    /** Fuel unit */
     const GALLONS_UK = 2;
 
-    // Consumption units
+    /** Consumption unit: l/100km */
     const L_PER_100KM = 0;
+    /** Consumption unit: mpg (us) */
     const MPG_US = 1;
+    /** Consumption unit: mpg (imp) */
     const MPG_UK = 2;
+    /** Consumption unit: km/l */
     const KM_PER_L = 3;
+    /** Consumption unit: km/gal (imp) */
     const KM_PER_GAL_US = 4;
+    /** Consumption unit: km/gal (us) */
     const KM_PER_GAL_UK = 5;
 
+    /** @var string Car name */
     protected $name;
+    
+    /** @var string Car description */
     protected $description;
+    
+    /** @var integer Distance unit */
     protected $distance_unit;
+    
+    /** @var integer Fuel unit */
     protected $fuel_unit;
+    
+    /** @var integer Consuption unit */
     protected $consumption_unit;
+    
+    /** @var string CSV date format, constant */
     protected $csv_date_format = 'dd.MM.yyyy';
+    
+    /** @var string Vehicle Identification Number */
     protected $vin;
+    
+    /** @var string Insurance policy number */
     protected $insurance;
+    
+    /** @var string Plate number */
     protected $plate;
+    
+    /** @var string Vehicle make */
     protected $make;
+    
+    /** @var string Vehicle model */
     protected $model;
+    
+    /** @var string Vehicle production year */
     protected $year;
 
+    /**
+     * Default constructor
+     * @param string $sName Car name
+     * @param string $sDescription Car description
+     * @param integer $iDistance_unit Distance unit constant
+     * @param integer $iFuel_unit Fuel unit constant
+     * @param integer $iConsumption_unit Consuption unit constant
+     */
     public function __construct($sName, $sDescription, $iDistance_unit = Vehicle::KILOMETERS, $iFuel_unit = Vehicle::LITRES, $iConsumption_unit = Vehicle::L_PER_100KM) {
         $this->setName($sName);
         $this->setDescription($sDescription);