[TIMOB-7871] modules API specification adjustments

iphone/AppledocSettings.plist

@@ -45,9 +45,7 @@
 		<string>Classes/TiBuffer.h</string>
 		<string>Classes/WebFont.h</string>
 		<string>Classes/Webcolor.h</string>
-		<string>Classes/TiRect.h</string>
 		<string>Classes/TiPoint.h</string>
-		<string>Classes/TiComplexValue.h</string>
 		<string>Classes/TiColor.h</string>
 		<string>Classes/Ti2DMatrix.h</string>
 		<string>Classes/ImageLoader.h</string>

iphone/Classes/ImageLoader.h

@@ -192,12 +192,12 @@ typedef enum {
 					   delegate:(NSObject<ImageLoaderDelegate>*)delegate 
 					   userInfo:(NSDictionary*)userInfo;
 
-/**
+/*
  Tells the image loader to suspend its activities.
  */
 -(void)suspend;
 
-/**
+/*
  Tells the image loader to resume its activities.
  */
 -(void)resume;

iphone/Classes/TiApp.h

@@ -90,7 +90,7 @@ TI_INLINE void waitForMemoryPanicCleared()   //WARNING: This must never be run o
  */
 +(TiApp*)app;
 
-/**
+/*
  Convenience method to returns root view controller for TiApp instance.
  @return The application's root view controller.
  @see controller

iphone/Classes/TiBuffer.h

@@ -36,17 +36,14 @@
 -(NSString*)toString:(id)_void;
 
 /**
- Returns the buffer length.
+ Provides access to the buffer length.
  */
-@property(nonatomic,readonly) NSNumber* length;
+@property(nonatomic,assign) NSNumber* length;
 
 /**
- Returns data byte order.
+ Provides access to the data byte order.
  */
-@property(nonatomic,readonly) NSNumber* byteOrder;
-
--(void)setLength:(NSNumber*)length;
--(void)setByteOrder:(NSNumber *)order;
+@property(nonatomic,retain) NSNumber* byteOrder;
 
 // SPECIAL NOTES:
 // Ti.Buffer objects have an 'overloaded' Ti.Buffer[x] operation for x==int (making them behave like arrays).

iphone/Classes/TiBuffer.m

@@ -323,14 +323,6 @@ -(NSNumber*)length
     return NUMINT([data length]);
 }
 
-- (void)setByteOrder:(NSNumber *)order
-{
-    if (byteOrder != order) {
-        [byteOrder release];
-        byteOrder = [order retain];
-    }
-}
-
 #pragma mark "operator[] overload" (Array behavior)
 
 -(void)setValue:(id)value forUndefinedKey:(NSString *)key

iphone/Classes/TiModule.h

@@ -34,7 +34,7 @@
 -(BOOL)isJSModule;
 -(NSData*)moduleJS;
 
-/**
+/*
  Converts a resource name in to a URL.
  @param name The name of the resource.
  @return The URL of the resource

iphone/Classes/TiProxy.h

@@ -132,15 +132,35 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView<TiProxyDelegate> * target
 -(id)_initWithPageContext:(id<TiEvaluator>)context;
 -(id)_initWithPageContext:(id<TiEvaluator>)context args:(NSArray*)args;
 -(void)_initWithProperties:(NSDictionary*)properties;
+
+/**
+ Whether or not the proxy has listeners for the specified event type.
+ @param type The event type.
+ @return _YES_ if the proxy has any listeners for the specified event type, _NO_ otherwise.
+ */
 -(BOOL)_hasListeners:(NSString*)type;
--(void)_fireEventToListener:(NSString*)type withObject:(id)obj listener:(KrollCallback*)listener thisObject:(TiProxy*)thisObject_;
+
+/**
+ Tells the proxy to fire an event of the specified type to a listener.
+ @param type The event type.
+ @param obj The event properties.
+ @param listener The listener to fire event for.
+ @param thisObject The object representing 'this' in the context of the event handler.
+ */
+-(void)_fireEventToListener:(NSString*)type withObject:(id)obj listener:(KrollCallback*)listener thisObject:(TiProxy*)thisObject;
+
 -(id)_proxy:(TiProxyBridgeType)type;
 -(void)contextWasShutdown:(id<TiEvaluator>)context;
 -(TiHost*)_host;
 -(NSURL*)_baseURL;
 -(void)_setBaseURL:(NSURL*)url;
 -(void)_destroy;
+
+/**
+ Called to perform the proxy initial configuration.
+ */
 -(void)_configure;
+
 -(void)_dispatchWithObjectOnUIThread:(NSArray*)args;
 -(void)didReceiveMemoryWarning:(NSNotification*)notification;
 -(TiProxy*)currentWindow;
@@ -210,10 +230,17 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView<TiProxyDelegate> * target
 #pragma mark Public 
 
 /**
- Returns all properties set on the proxy.
+ Returns an enumeration of keys of all properties set on the proxy object.
+ @return The enumeration of property keys.
  */
 -(id<NSFastEnumeration>)allKeys;
 
+/**
+ Returns the order of properties on the proxy object.
+ 
+ Should be overrided in the views where the order in which keys are applied matters.
+ @return The array of property keys.
+ */
 -(NSArray *)keySequence;
 
 +(void)throwException:(NSString *) reason subreason:(NSString*)subreason location:(NSString *)location;
@@ -227,9 +254,31 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView<TiProxyDelegate> * target
 -(void)fireEvent:(NSString*)type withObject:(id)obj withSource:(id)source propagate:(BOOL)yn;
 -(void)fireEvent:(NSString*)type withObject:(id)obj propagate:(BOOL)yn;
 
+/**
+ Returns a dictionary of all properties set on the proxy object.
+ @return The dictionary containing all properties.
+ */
 -(NSDictionary*)allProperties;
+
+/**
+ Initializes a new property on the proxy object.
+ @param name The property name.
+ @param value The initial value to set on the property.
+ */
 -(void)initializeProperty:(NSString*)name defaultValue:(id)value;
+
+/**
+ Sets or replaces the property on the proxy object.
+ @param value The new value.
+ @param key The property key.
+ @param notify The flag to send value chnage notification to model delegate.
+ */
 -(void)replaceValue:(id)value forKey:(NSString*)key notification:(BOOL)notify;
+
+/**
+ Removes the property on the proxy object.
+ @param key The property key.
+ */
 -(void)deleteKey:(NSString*)key;
 
 -(id)sanitizeURL:(id)value;

iphone/Classes/TiRootViewController.h

@@ -62,7 +62,7 @@
  */
 @property(nonatomic,readonly) BOOL keyboardVisible;
 
-/**
+/*
  Returns image view being displayed while application's view is loading.
  */
 @property(nonatomic,readonly) UIImageView * defaultImageView;
@@ -78,13 +78,13 @@
  */
 -(void)dismissDefaultImageView;
 
-/**
+/*
  Provides access to background color of the view represented by the root view controller.
  @see backgroundImage
  */
 @property(nonatomic,readwrite,retain)	UIColor * backgroundColor;
 
-/**
+/*
  Provides access to background image of the view represented by the root view controller.
  @see backgroundColor
  */
@@ -119,7 +119,14 @@
 
 -(void)refreshOrientationWithDuration:(NSTimeInterval) duration;
 -(NSTimeInterval)suggestedRotationDuration;
+
+/**
+ Tells the controller to perform rotation to the specified orientation.
+ @param newOrientation The new orientation.
+ @param duration The rotation animation duration.
+ */
 -(void)manuallyRotateToOrientation:(UIInterfaceOrientation)newOrientation duration:(NSTimeInterval)duration;
+
 -(UIInterfaceOrientation)lastValidOrientation;
 
 /**

iphone/Classes/TiUIView.h

@@ -154,7 +154,7 @@ void ModifyScrollViewForKeyboardHeightAndContentHeightWithResponderRect(UIScroll
 -(void)setVirtualParentTransform:(CGAffineTransform)newTransform;
 -(void)setTransform_:(id)matrix;
 
-/**
+/*
  Tells the view to load an image.
  @param image The string referring the image.
  @return The loaded image.
@@ -164,7 +164,7 @@ void ModifyScrollViewForKeyboardHeightAndContentHeightWithResponderRect(UIScroll
 -(id)proxyValueForKey:(NSString *)key;
 -(void)readProxyValuesWithKeys:(id<NSFastEnumeration>)keys;
 
-/**
+/*
  Tells the view to change its proxy to the new one provided.
  @param newProxy The new proxy to set on the view.
  */

iphone/Classes/TiUtils.h

@@ -431,6 +431,11 @@ typedef enum {
 
 +(CGRect)centerRect:(CGRect)smallerRect inRect:(CGRect)largerRect;
 
+/**
+ Sets the view's bounds and center coordinates.
+ @param view The view to make changes on.
+ @param frameRect The rectangle containing bounds to apply to the view.
+ */
 +(void)setView:(UIView *)view positionRect:(CGRect)frameRect;
 
 +(CGRect)viewPositionRect:(UIView *)view;
@@ -449,10 +454,22 @@ typedef enum {
  */
 +(BOOL)isIPad;
 
+/**
+ Whether or not the current OS version is equal or greather than 4.2.
+ @return _YES_ if the current OS version is equal or greather than 4.2, _NO_ otherwise.
+ */
 +(BOOL)isIOS4_2OrGreater;
 
+/**
+ Whether or not the current OS version is equal greather than 5.0.
+ @return _YES_ if the current OS version is equal greather than 5.0, _NO_ otherwise.
+ */
 +(BOOL)isIOS5OrGreater;
 
+/**
+ Whether or not the current device is iPhone 4.
+ @return _YES_ if the current device is iPhone 4, _NO_ otherwise.
+ */
 +(BOOL)isIPhone4;
 
 /**

iphone/Classes/TiViewProxy.h

@@ -122,7 +122,8 @@ enum
 }
 
 #pragma mark public API
-/**
+
+/*
  Provides access to z-index value.
  */
 @property(nonatomic,readwrite,assign) int vzIndex;
@@ -487,6 +488,9 @@ enum
  */
 -(void)refreshPosition;
 
+/**
+ Puts the view in the layout queue for rendering.
+ */
 -(void)willEnqueue;
 
 //Unlike the other layout actions, this one is done by the parent of the one called by refreshView.
@@ -497,15 +501,34 @@ enum
 #pragma mark Layout commands that need refactoring out
 
 -(void)determineSandboxBounds;
+
+/**
+ Tells the view to layout its children.
+ @param optimize Internal use only. Always specify _NO_.
+ */
 -(void)layoutChildren:(BOOL)optimize;
+
+/**
+ Tells the view to layout its childrent only if there were any layout chnages.
+ */
 -(void)layoutChildrenIfNeeded;
+
 -(void)layoutChild:(TiViewProxy*)child optimize:(BOOL)optimize;
 
+/**
+ Tells the view to adjust its size and position according to the current layout constraints.
+ */
 -(void)relayout;
+
 -(void)insertIntoView:(UIView*)view bounds:(CGRect)bounds;
 -(void)reposition;	//Todo: Replace
 
 -(BOOL)willBeRelaying;	//Todo: Replace
+
+/**
+ Tells the view that its child view size will change.
+ @param child The child view
+ */
 -(void)childWillResize:(TiViewProxy *)child;	//Todo: Replace
 
 @end