more Doxygen tags and comments

@@ -31,7 +31,7 @@
 
 @class RMTileCache;
 
-// Simple wrapper around a tilesource which checks the image cache first.
+/// Simple wrapper around a tilesource which checks the image cache first.
 @interface RMCachedTileSource : NSObject<RMTileSource>
 {
 	id <RMTileSource> tileSource;

@@ -161,6 +161,7 @@
 	return image;
 }
 
+/// FIXME: shouldn't reinitialize database in a low-memory warning
 -(void)didReceiveMemoryWarning
 {
 	LogMethod();		

@@ -28,6 +28,7 @@
 #import <Foundation/Foundation.h>
 #import "RMTileImage.h"
 
+/// a tile image loaded from a local file
 @interface RMFileTileImage : RMTileImage {
 
 }

@@ -69,6 +69,7 @@ enum {
 @end
 
 
+/// The cartographic and data components of a map. There is exactly one RMMapContents instance for each RMMapView instance.
 @interface RMMapContents : NSObject
 {
 	// TODO: Also support NSView.
@@ -107,6 +108,13 @@ enum {
 @property (readwrite) RMXYRect XYBounds;
 @property (readonly)  RMTileRect tileBounds;
 @property (readonly)  CGRect screenBounds;
+/*! \brief "scale" as of version 0.4/0.5 actually doesn't mean cartographic scale; it means meters per pixel.
+ 
+ "Scale" is how many meters in 1 pixel. Larger scale means bigger things are smaller on the screen.
+ "Scale" of 1 means 1 pixel == 1 meter.
+ "Scale" of 10 means 1 pixel == 10 meters.
+ \deprecated will be renamed appropriately and a new -scale method introduced, using cartographic scale (e.g. 1:24000).
+ */
 @property (readwrite) float scale;
 @property (readwrite) float zoom;
 

@@ -89,7 +89,8 @@ svn checkout http://route-me.googlecode.com/svn/trunk/ route-me-read-only
 #import "RMMapViewDelegate.h"
 #import "RMMapContents.h"
 
-/*! \struct RMGestureDetails
+/*! 
+ \struct RMGestureDetails
  iPhone-specific mapview stuff. Handles event handling, whatnot.
  */
 typedef struct {
@@ -103,7 +104,7 @@ typedef struct {
 /*! 
  \brief Wrapper around RMMapContents for the iPhone.
  It implements event handling; but that's about it. All the interesting map
- logic is done by RMMapContents.
+ logic is done by RMMapContents. There is exactly one RMMapView instance for each RMMapContents instance.
  */
 @interface RMMapView : UIView <RMMapContentsFacade, RMMapContentsAnimationCallback>
 {

@@ -30,6 +30,7 @@
 @class RMMapView;
 @class RMMarker;
 
+/// Use this for notifications of map panning, zooming, and taps on the RMMapView.
 @protocol RMMapViewDelegate 
 
 @optional
@@ -48,7 +49,7 @@
 - (BOOL) mapView:(RMMapView *)map shouldDragMarker:(RMMarker *)marker withEvent:(UIEvent *)event;
 - (void) mapView:(RMMapView *)map didDragMarker:(RMMarker *)marker withEvent:(UIEvent *)event;
 
-// The following call is depreciated, please use didDragMarker instead.  This call will no longer exist after the .5 Milestone
+/// \brief \deprecated This call is deprecated, please use didDragMarker instead.  This call will no longer exist after the .5 Milestone
 - (void) dragMarkerPosition: (RMMarker*) marker onMap: (RMMapView*)map position:(CGPoint)position;
 
 

@@ -36,5 +36,7 @@
 }
 
 -(id)initWithCapacity: (NSUInteger) _capacity;
+/// Remove the least-recently used image from cache, if cache is at or over capacity. Removes only 1 image.
+-(void)makeSpaceInCache;
 
 @end

@@ -88,6 +88,7 @@
 	return image;
 }
 
+/// Remove the least-recently used image from cache, if cache is at or over capacity. Removes only 1 image.
 -(void)makeSpaceInCache
 {
 	while ([cache count] >= capacity)

@@ -33,18 +33,26 @@
 #include <stdint.h>
 
 /*! \struct RMTile
- Uniquely specifies coordinates and zoom level for a particular tile in some tile source.
+ \brief Uniquely specifies coordinates and zoom level for a particular tile in some tile source.
+ 
+ This is a 3-field number. If you want the image associated with an RMTile, you're looking for RMTileImage
  */
 typedef struct{
 	uint32_t x, y;
 	short zoom;
 } RMTile;
 
+/*! \struct RMTilePoint
+ \brief Don't know what this is for.
+ */
 typedef struct{
 	RMTile tile;
 	CGPoint offset;
 } RMTilePoint;
 
+/*! \struct RMTileRect
+ \brief Don't know what this is for.
+ */
 typedef struct{
 	RMTilePoint origin;
 	CGSize size;
@@ -55,19 +63,19 @@ char RMTilesEqual(RMTile one, RMTile two);
 char RMTileIsDummy(RMTile tile);
 RMTile RMTileDummy();
 
-// Return a hash of the tile
+/// Return a hash of the tile
 uint64_t RMTileHash(RMTile tile);
 
-// Returns a unique key of the tile
+/// Returns a unique key of the tile for use in the SQLite cache
 uint64_t RMTileKey(RMTile tile);
 
-// Round the rectangle to whole numbers of tiles
+/// Round the rectangle to whole numbers of tiles
 RMTileRect RMTileRectRound(RMTileRect rect);
 /*
-// Calculate and return the intersection of two rectangles
+/// Calculate and return the intersection of two rectangles
 TileRect TileRectIntersection(TileRect one, TileRect two);
 
-// Calculate and return the union of two rectangles
+/// Calculate and return the union of two rectangles
 TileRect TileRectUnion(TileRect one, TileRect two);
 */
 #endif

@@ -62,6 +62,11 @@ typedef enum {
 +(NSNumber*) tileHash: (RMTile)tile;
 
 /// Add tile to cache
+/*! 
+ \bug Calls -makeSpaceInCache for every tile/image addition. -makeSpaceInCache does a linear scan of its contents at each call.
+
+ \bug Since RMTileImage has an RMTile ivar, this API should be simplified to just -addImage:.
+ */
 -(void)addTile: (RMTile)tile WithImage: (RMTileImage*)image;
 
 /// Add another cache to the chain

@@ -29,6 +29,7 @@
 
 @class FMDatabase;
 
+/// the interface between RMDatabaseCache and FMDB
 @interface RMTileCacheDAO : NSObject {
 	FMDatabase* db;	
 }

@@ -53,11 +53,14 @@ extern NSString * const RMMapImageLoadingCancelledNotification;
 	RMTile tile;
 	CGRect screenLocation;
 	
+	/// \deprecated appears to be cruft
 	int loadingPriorityCount;
 	
-	// Used by cache
+	/// Used by cache
 	NSDate *lastUsedTime;
 	
+	/// \bug placing the "layer" on the RMTileImage implicitly assumes that a particular RMTileImage will be used in only 
+	/// one UIView. Might see some interesting crashes if you have two RMMapViews using the same tile source.
 	// Only used when appropriate
 	CALayer *layer;
 }

@@ -29,10 +29,13 @@
 #import "RMTile.h"
 
 @class RMTileImage;
+/// Has only class methods defined, to return generic "error image", "not-yet-loaded image", and proxy images.
+/// \bug This functionality belongs on the tile source, and should not be freestanding.
 @interface RMTileProxy : NSObject {
 	
 }
 
+/// \deprecated hardcoded to return nil
 +(RMTileImage*) bestProxyFor: (RMTile) t;
 +(RMTileImage*) errorTile;
 +(RMTileImage*) loadingTile;

@@ -31,8 +31,7 @@
 
 @protocol RMTileSource;
 
-////////////////////////////// NOT COMPLETE. DO NOT USE
-
+/// ////////////////////////// NOT COMPLETE. DO NOT USE
 @interface RMTiledLayerController : NSObject
 {
 	CATiledLayer *layer;

@@ -28,6 +28,7 @@
 #import <Foundation/Foundation.h>
 #import "RMTileImage.h"
 
+/// a tile image loaded from a URL
 @interface RMWebTileImage : RMTileImage {
 	/// Before image is completely loaded a proxy image can be used.
 	/// This will typically be a boilerplate image or a zoomed in or zoomed out version of another image.