Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documenting the gravatar service API

  • Loading branch information...
commit 2f28e29d55c019ed5dc226253e6e14880802d72a 1 parent 6523a59
Magnus Ernstsson authored
View
56 Interface/GravatarService.h
@@ -8,26 +8,78 @@
#import <Foundation/Foundation.h>
+/**
+ * Service protocol implemented by all GitHub services returned by the GitHub
+ * service factories.
+ */
@protocol GravatarService <NSObject>
+/**
+ * Property containing for the requested email address, if email is requested.
+ */
@property (readonly, copy) NSString *email;
+
+/**
+ * Property containing for the requested gravatar id.
+ */
@property (readonly, copy) NSString *gravatarid;
+/**
+ * Cancelles the request to the service. If cancelled, no more message will be
+ * sent to the delegate.
+ */
-(void)cancelRequest;
@end
+/**
+ * Error domain string used when gravtarService:didFailWithError: is called.
+ */
extern NSString * const GravatarServerErrorDomain;
typedef enum {
- GravatarServerServerError = 1,
- GravatarServerConnectionError = 2,
+ GravatarServerServerError = 1, /**< Error recieved from the server */
+ GravatarServerConnectionError = 2, /**< Error connecting to server */
} GravatarServerError;
+/**
+ * Default default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageDefault;
+
+/**
+ * 404 default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImage404;
+
+/**
+ * MysteryMan default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageMysteryMan;
+
+/**
+ * Identicon default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageIdenticon;
+
+/**
+ * Monster default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageMonsterId;
+
+/**
+ * Wavatar default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageWavatar;
+
+/**
+ * Retro default gravatar image.
+ * See the gravatar API documentation for details.
+ */
extern NSString * const gravatarServerImageRetro;
View
19 Interface/GravatarServiceDelegate.h
@@ -10,10 +10,29 @@
#import <UIKit/UIKit.h>
#import "GravatarService.h"
+/**
+ * Service delegate protocol used by the gravatar services to return responses
+ * asyncronosly.
+ */
@protocol GravatarServiceDelegate
+
+/**
+ * Called when the gravatar service is successfully done.
+ * Will not be called if the service is cancelled using cancelRequest.
+ * Will not be called after gravatarService:didFailWithError: has been called.
+ * @param gravatarService The completed service.
+ * @param image The UIImage containing the requested image data.
+ */
-(void)gravatarServiceDone:(id<GravatarService>)gravatarService
withImage:(UIImage *)image;
+/**
+ * Called if an error occurs in the gravatar service.
+ * Will not be called if the service is cancelled using cancelRequest.
+ * Will not be called after gravatarServiceDone:withImage: has been called.
+ * @param gravatarService The service returning the error.
+ * @param error The error that occured, according to GravatarServerError.
+ */
-(void)gravatarService:(id<GravatarService>)gravatarService
didFailWithError:(NSError *)error;
@end
View
67 Interface/GravatarServiceFactory.h
@@ -11,24 +11,87 @@
#import "GravatarService.h"
#import "GravatarServiceDelegate.h"
+/**
+ * Service factory class for the gravatar services.
+ */
@interface GravatarServiceFactory : NSObject {
}
+/**
+ * Creates and returns an initialized GravatarService that will return a
+ * UIImage using the delegate method gravatarServiceDone:withImage if
+ * successful. If the service failed during execution
+ * gitHubService:didFailWithError: will be called instead.
+ * Can be cancelled using cancelRequest. If cancelled, no more message will be
+ * sent to the delegate.
+ * @param gravatarId The precalculated gravatar id to get a UIImage from.
+ * @param defaultImage The default image to use if a gravatar is not registered.
+ * One of the predefiend gravatarServerImages can be used
+ * or a url could be specified.
+ * @param size The size of the requested image. Images are always square.
+ * Needs to be between 1 and 512 pixels.
+ * @param delegate The delegate object for the service.
+ * @return The service for the request.
+ */
+(id<GravatarService>)requestUIImageByGravatarId:(NSString *)gravtarId
defaultImage:(NSString *)defaultImage
size:(NSInteger)size
delegate:(id<GravatarServiceDelegate>)delegate;
+/**
+ * Creates and returns an initialized GravatarService that will return a
+ * default sized UIImage using the delegate method gravatarServiceDone:withImage
+ * if successful. If the service failed during execution
+ * gitHubService:didFailWithError: will be called instead.
+ * Can be cancelled using cancelRequest. If cancelled, no more message will be
+ * sent to the delegate.
+ * @param gravatarId The precalculated gravatar id to get a UIImage from.
+ * @param defaultImage The default image to use if a gravatar is not registered.
+ * One of the predefiend gravatarServerImages can be used
+ * or a url could be specified.
+ * @param delegate The delegate object for the service.
+ * @return The service for the request.
+ */
+(id<GravatarService>)requestUIImageByGravatarId:(NSString *)gravtarId
defaultImage:(NSString *)defaultImage
delegate:(id<GravatarServiceDelegate>)delegate;
-+(id<GravatarService>)requestUIImageByEmail:(NSString *)gravtarId
+/**
+ * Creates and returns an initialized GravatarService that will return a
+ * UIImage using the delegate method gravatarServiceDone:withImage if
+ * successful. If the service failed during execution
+ * gitHubService:didFailWithError: will be called instead.
+ * Can be cancelled using cancelRequest. If cancelled, no more message will be
+ * sent to the delegate.
+ * @param email The email address to get a UIImage from.
+ * @param defaultImage The default image to use if a gravatar is not registered.
+ * One of the predefiend gravatarServerImages can be used
+ * or a url could be specified.
+ * @param size The size of the requested image. Images are always square.
+ * Needs to be between 1 and 512 pixels.
+ * @param delegate The delegate object for the service.
+ * @return The service for the request.
+ */
++(id<GravatarService>)requestUIImageByEmail:(NSString *)email
defaultImage:(NSString *)defaultImage
size:(NSInteger)size
delegate:(id<GravatarServiceDelegate>)delegate;
-+(id<GravatarService>)requestUIImageByEmail:(NSString *)gravtarId
+/**
+ * Creates and returns an initialized GravatarService that will return a
+ * default sized UIImage using the delegate method gravatarServiceDone:withImage
+ * if successful. If the service failed during execution
+ * gitHubService:didFailWithError: will be called instead.
+ * Can be cancelled using cancelRequest. If cancelled, no more message will be
+ * sent to the delegate.
+ * @param email The email address to get a UIImage from.
+ * @param defaultImage The default image to use if a gravatar is not registered.
+ * One of the predefiend gravatarServerImages can be used
+ * or a url could be specified.
+ * @param delegate The delegate object for the service.
+ * @return The service for the request.
+ */
++(id<GravatarService>)requestUIImageByEmail:(NSString *)email
defaultImage:(NSString *)defaultImage
delegate:(id<GravatarServiceDelegate>)delegate;
Please sign in to comment.
Something went wrong with that request. Please try again.