Document extendable clases

Patch also changes class, method and property names based on the coding standards http://drupal.org/node/608152 and defines the main public methods in an interface (as per page). As the module already requires PHP 5.2 it drops all the PHP 4 class definitions.

Functionality has intentionally not been changed. With one patch to the tests (for the class name - also attached) they run the same. It would be nice, if maintainers are agreeable, to investigate changing the error reporting from geocode method, adding more helper functions into GeocodeBasic for json (and xml) parser error handling. Certainly it would make it easier from what little I've done developing on a Geonames class. Using ctools for loading would be cool too maybe?

Naturally.

Last one from me until feedback I promise. But does it make sense that the geocoder (not the geocoder_widget) is more consistent with the geo module? Something like:-

interface GeocodeInterface {
  /**
   * Define available geometry this geocoder can work with.
   *
   * @return
   *   array of geometry (and postal) types this geocoder can work from and to.
   */
  static function options();

  /**
   * Get and set methods
   */

  /**
   * Set a geometry point.
   *
   * @param
   *  class GeometryPoint
   */
  public function setPoint(GeometryPoint $point);

  /**
   * Return a (geocoded) GeomentryPoint object.
   *
   * @return
   *  class GeometryPoint.
   */
  public function getPoint();

  /**
   * Set a polygon.
   *
   * @param
   *  class GeometryPolygon
   */
  public function setPolygon(GeometryPolygon $polygon);

  /**
   * Return a (geocoded) GeometryPolygon
   *
   * @return
   *  class GeometryPolygon.
   */
  public function getPolygon();

  /**
   * Set a linestring.
   *
   * @param
   *  class GeometryLinestring.
   */
  public function setLinestring(GeometryLinestring $linestring);

  /**
   * Set a postal location.
   *
   * @todo describe class (just $postal->street1, $postal->street2 etc. probably).
   *
   * @param
   *  stdClass postal location.
   */
  public function setPostal(stdClass $postal)

  /**
   * Return a stdClass with postal location.
   *
   * @return
   *   class postal location.
   */
  public function getPostal();

  /**
   * Geocode (from) and to methods.
   */

  /**
   * Geocode.
   *
   * Geocode between types. Default to attempt with all set properties
   * to all possible, supported, properties. Which and how much choice 
   * is possible, or desirable, will depend on the individual geocoder.
   *
   * @param $to
   *  (optional, variable number) which elements to map to.
   * @throws
   *  error on failure to retrieve, parse or geocode.
   */
  public function geocode();

  /**
   * Geocode input.
   *
   * Geocode from input. Default to all supported. 
   *
   * @param $input
   *  input to geocode, usually going to be a string, or pointer 
   *  to a to an item (gpx file, image file, node content maybe, etc.) to parse.
   * @param $to
   *  (optional, variable) which elements to geocode to.
   * @throws
   *  error on failure.
   */
  public function geocodeInput($input);
}

I've not quite got my head round the creation of the GeometryTypes. I take it there's a factory that I'm not quite using right, or needs a bit of tweaking for GeometrySimple for this case? But it seems it would then make it easier for modules using the geo api to convert consistently to what they need? Just a thought, if it's a good idea, I'll happily help. Other ideas good to :)

Short follow up on #3. I've thought the same simple classes for geometry types would help here #623428: Provide hook_feeds_user_processor_targets_alter() see comment #21 Any feedback would be great.