tweak docblocks

src/Buonzz/GeoIP/GeoIP.php

@@ -1,75 +1,155 @@
 <?php namespace Buonzz\GeoIP;
+
 /**
-*  A sample class
+*  Contains all the method to retrieve data from freegeoip.net.
 *
-*  Use this section to define what this class is doing, the PHPDocumentator will use this
-*  to automatically generate an API documentation using this information.
+*  This contains the geoip data as well all the marshalling mechanism from 
+*  the web service.
 *
-*  @author yourname
+*  @author Darwin Biler <[email protected]>
 */
 class GeoIP{
 
+
+  /**  @var mixed $geoip_data  contains the JSON object retrieved from the API */
   private $geoip_data = NULL;
+
+  /**  @var string $ip contains the IP of the current visitor */
   private $ip;
 
+
+  /**
+  * constructor which initialiazes various things.
+  *
+  * detects if the REMOTE_ADDR is present (usually not, when running in cli or phpunit)
+  * if present use that one.
+  *
+  * @return void
+  */
   public function __construct(){
       if(isset($_SERVER['REMOTE_ADDR']))
           $this->ip = $_SERVER['REMOTE_ADDR'];     
   }
 
+  /**
+  * allows the user to set the IP to be process instead of retrieving it from server.
+  *
+  * @return void
+  */
   public function setIP($ip){
     $this->ip = $ip;
   }
 
-   public function getCountry(){
+  /**
+  * get the descriptive name of the country.
+  *
+  * @return string
+  */
+  public function getCountry(){
 			return $this->getItem('country_name');
    }
 
-   public function getCountryCode(){
+  /**
+  * get the 2-letter code  of the country.
+  *
+  * @return string
+  */
+  public function getCountryCode(){
       return $this->getItem('country_code');
    }
 
-   public function getRegionCode(){
+  /**
+  * get the region code.
+  *
+  * @return string
+  */
+  public function getRegionCode(){
       return $this->getItem('region_code');
    }
 
+  /**
+  * get the descriptive name of the region.
+  *
+  * @return string
+  */
    public function getRegion(){
        return $this->getItem('region_name');
    }
 
-   public function getCity(){
+  /**
+  * get the descriptive name of the City.
+  *
+  * @return string
+  */
+  public function getCity(){
        return $this->getItem('city');
    }
 
-   public function getZipCode(){
+  /**
+  * get the zip code.
+  *
+  * @return string
+  */
+  public function getZipCode(){
        return $this->getItem('zipcode');
    }
 
-   public function getLatitude(){
+  /**
+  * get the latitude of the location.
+  *
+  * @return double
+  */
+  public function getLatitude(){
        return $this->getItem('latitude');
    }
 
-   public function getLongitude(){
+  /**
+  * get the longitude of the location.
+  *
+  * @return double
+  */
+  public function getLongitude(){
       return $this->getItem('longitude');
    }
 
-   public function getMetroCode(){
+  /**
+  * get the metro code.
+  *
+  * @return string
+  */
+  public function getMetroCode(){
      return $this->getItem('metro_code');
    }
 
-   public function getAreaCode(){
+
+  /**
+  * get the area code.
+  *
+  * @return string
+  */
+  public function getAreaCode(){
       return $this->getItem('area_code');
    }
 
-   private function getItem($name){      
+  /**
+  * generic property retriever.
+  *
+  * @return string
+  */
+  private function getItem($name){      
 
         if($this->geoip_data == NULL)
           $this->retrievefromCache();
 
         return $this->geoip_data->$name;
    }
 
-   private function retrievefromCache(){      
+  /**
+  * check if the Cache class exists and use caching mechanism if there is, otherwise just call the API directly.
+  *
+  * @return void
+  */
+  private function retrievefromCache(){      
 
       if (class_exists('\\Cache'))
       {
@@ -88,6 +168,14 @@ private function retrievefromCache(){
            $this->geoip_data = $this->resolve($this->ip);
    }
 
+
+  /**
+  * call the freegeoip.net for data, retrieve it as JSON and convert it to stdclass.
+  *
+  * @todo make this thing use Guzzle instead, you novice kid!
+  *
+  * @return void
+  */
    function resolve($ip){
 
       $url = 'https://freegeoip.net/json/'.$ip;

src/Buonzz/GeoIP/Laravel4/Facades/GeoIP.php

@@ -3,16 +3,18 @@
 use Illuminate\Support\Facades\Facade;
 
 /**
-*  Facade class for your Class
+*  Facade class for the GeoIP.
 *
 *  Use this to provide a facade for Laravel Application
 *
 *  @author Darwin Biler <[email protected]>
 */
 class GeoIP extends Facade{
    /**
-   *  method to be called to return the "real" class, since facade is just a front
-   *  note that the yourclass is lowercase, since that is what we had registered in the ServiceProvider
+   *  method to be called to return the "real" class, since facade is just a syntax sugar.
+   *  Note that the geoip is lowercase, since that is what we had registered in the ServiceProvider
+   *
+   *  @return mixed the class name we had registered in the serviceprovider
    */
    protected static function getFacadeAccessor(){ return 'geoip';}
 }

src/Buonzz/GeoIP/Laravel4/ServiceProviders/GeoIPServiceProvider.php

@@ -4,10 +4,11 @@
 use Buonzz\GeoIP\GeoIP as GeoIP;
 
 /**
-*  The Laravel4 Service provider to bing your class to the IoC container
+*  Binds the GeoIP class to the IoC container.
 *
-*  This makes it possible for Laravel to find your classes in the App object
-*  like App::make('YourClass');
+*  This makes it possible for Laravel to find the GeoIP in the App object
+*  like App::make('GeoIP');
+*  the same binding is also used by facade to resolve the class
 *  
 */
 class GeoIPServiceProvider extends ServiceProvider{

tests/Unit/Buonzz/GeoIP/GeoIPTest.php

@@ -1,17 +1,15 @@
 <?php 
 
 /**
-*  Corresponding Class to test YourClass class
+*  Corresponding Class to test GeoIP class.
 *
-*  For each class in your library, there should be a corresponding Unit-Test for it
-*  Unit-Tests should be as much as possible independent from other test going on.
 *
-*  @author yourname
+*  @author Darwin Biler <[email protected]>
 */
 class GeoIPTest extends PHPUnit_Framework_TestCase{
 
   /**
-  * Just check if the YourClass has no syntax error 
+  * Just check if the YourClass has no syntax error. 
   *
   * This is just a simple check to make sure your library has no syntax error. This helps you troubleshoot
   * any typo before you even use this library in a real project.
@@ -24,6 +22,12 @@ public function testIsThereAnySyntaxError(){
   }
 
 
+  /**
+  * Just check if the GeoIP can retrieve Country info.
+  *
+  * I hardcoded here one of my dynamic ip and see if it will return my country name
+  *
+  */
   public function testgetCountry(){
   	$var = new Buonzz\GeoIP\GeoIP;
     $var->setIP('112.209.247.183');