Documenting image library interfaces

gfx/src/nsIImageGroup.h

@@ -29,13 +29,13 @@ class nsIImageRequestObserver;
 class nsIImageRequest;
 class nsIRenderingContext;
 
-/* For important images, like backdrops. */
+/** For important images, like backdrops. */
 #define nsImageLoadFlags_kHighPriority  0x01   
-/* Don't throw this image out of cache.  */
+/** Don't throw this image out of cache.  */
 #define nsImageLoadFlags_kSticky        0x02   
-/* Don't get image out of image cache.   */
+/** Don't get image out of image cache.   */
 #define nsImageLoadFlags_kBypassCache   0x04   
-/* Don't load if image cache misses.     */
+/** Don't load if image cache misses.     */
 #define nsImageLoadFlags_kOnlyFromCache 0x08   
 
 // IID for the nsIImageGroup interface
@@ -43,50 +43,75 @@ class nsIRenderingContext;
 { 0xbe927e40, 0xaeaa, 0x11d1,  \
 { 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
 
-//----------------------------------------------------------------------
+/**
-// 
+ *
-// Image group. A convenient way to group a set of image load requests
+ * Image group. A convenient way to group a set of image load requests
-// and control them as a group.
+ * and control them as a group.
+ */
 class nsIImageGroup : public nsISupports
 {
 public:
+  /**
+   * Initialize an image group with a rendering context. All images
+   * in this group will be decoded for the specified rendering context.
+   */
   virtual nsresult Init(nsIRenderingContext *aRenderingContext) = 0;
 
-  // Add and remove observers to listen in on image group notifications
+  /** 
+   * Add an observers to be informed of image group notifications.
+   *
+   * @param aObserver - An observer to add to the observer list.
+   * @param boolean indicating whether addition was successful.
+   */
   virtual PRBool AddObserver(nsIImageGroupObserver *aObserver) = 0;
+
+  /**
+   * Remove a previously added observer from the observer list.
+   *
+   * @param aObserver - An observer to remove from the observer list.
+   * @param boolean indicating whether the removal was successful.
+   */ 
   virtual PRBool RemoveObserver(nsIImageGroupObserver *aObserver) = 0;
 
-  // Fetch the image corresponding to the specified URL. 
+  /**
-  // 
+   *  Fetch the image corresponding to the specified URL. 
-  // The observer is notified at significant points in image loading.
+   * 
-  // 
+   *  @param aUrl - the URL of the image to be loaded.
-  // The width and height parameters specify the target dimensions of
+   *  @param aObserver - the observer is notified at significant 
-  // the image.  The image will be stretched horizontally, vertically or
+   *       points in image loading.
-  // both to meet these parameters.  If both width and height are zero,
+   *  @param aWidth, aHeight - These parameters specify the target 
-  // the image is decoded using its "natural" size.  If only one of
+   *       dimensions of the image.  The image will be stretched 
-  // width and height is zero, the image is scaled to the provided
+   *       horizontally, vertically or both to meet these parameters.  
-  // dimension, with the unspecified dimension scaled to maintain the
+   *       If both width and height are zero, the image is decoded 
-  // image's original aspect ratio.
+   *       using its "natural" size.  If only one of width and height 
-  //  
+   *       is zero, the image is scaled to the provided dimension, with
-  // If the background color is NULL, a mask will be generated for any
+   *       the unspecified dimension scaled to maintain the image's 
-  // transparent images.  If background color is non-NULL, it indicates 
+   *       original aspect ratio.
-  // the RGB value to be painted into the image for "transparent" areas 
+   *  @param aBackgroundColor - If the background color is NULL, a mask 
-  // of the image, in which case no mask is created.  This is intended 
+   *       will be generated for any transparent images.  If background 
-  // for backdrops and printing.
+   *       color is non-NULL, it indicates the RGB value to be painted 
-  //
+   *       into the image for "transparent" areas of the image, in which 
-  // Image load flags are specified above
+   *       case no mask is created.  This is intended for backdrops and 
+   *       printing.
+   *  @param aFlags - image loading flags are specified above
+   *
+   *  @return the resulting image request object.
+   */
   virtual nsIImageRequest* GetImage(const char* aUrl, 
                                     nsIImageRequestObserver *aObserver,
                                     nscolor aBackgroundColor,
                                     PRUint32 aWidth, PRUint32 aHeight,
                                     PRUint32 aFlags) = 0;
 
-  // Halt decoding of images or animation without destroying associated
+  /**
-  // pixmap data. All ImageRequests created with this ImageGroup
+   *  Halt decoding of images or animation without destroying associated
-  // are interrupted.
+   *  pixmap data. All ImageRequests created with this ImageGroup
+   *  are interrupted.
+   */
   virtual void Interrupt(void) = 0;
 };
 
+/// Factory method for creating an image group
 extern NS_GFX nsresult
   NS_NewImageGroup(nsIImageGroup **aInstancePtrResult);                   
 

gfx/src/nsIImageManager.h

@@ -38,29 +38,45 @@ typedef enum
 { 0x9f327100, 0xad5a, 0x11d1,   \
 { 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
 
-//----------------------------------------------------------------------
+/**
-// 
+ *
-// Image manager. There is only a single instance, created when the
+ * Image manager. There is only a single instance, returned when invoking
-// class is initially loaded. 
+ * the factory instantiation method. A user of the image library should
+ * hold on to the singleton image manager.
+ */
 class nsIImageManager : public nsISupports
 {
 public:
+  /// Initialization method to be called before use
   virtual nsresult Init() = 0;
 
-  // Set and get the cache size in bytes
+  /// Set the size (in bytes) image cache maintained by the image manager
   virtual void SetCacheSize(PRInt32 aCacheSize) = 0;
+
+  /// @return the current size of the image cache (in bytes)
   virtual PRInt32 GetCacheSize(void) = 0;
   
-  // Attempts to release some memory by freeing an image from the image
+  /**
-  // cache.  This may not always be possible either because all images
+   *  Attempts to release some memory by freeing an image from the image
-  // in the cache are in use or because the cache is empty.  Returns the
+   *  cache.  This may not always be possible either because all images
-  // new approximate size of the imagelib cache. 
+   *  in the cache are in use or because the cache is empty.  
+   *
+   *  @return the new approximate size of the imagelib cache. 
+   */
   virtual PRInt32 ShrinkCache(void) = 0;
 
-  // Determine the type of the image, based on the first few bytes of data.  
+  /**
+   * Determine the type of the image, based on the first few bytes of data.  
+   *
+   * @param buf - a buffer of image data
+   * @param length - the length of the buffer
+   *
+   * @return the type of the image, if known
+   */
   virtual nsImageType GetImageType(const char *buf, PRInt32 length) = 0;
 };
 
+/// Factory method to get a reference to the singleton image manager
 extern NS_GFX nsresult
   NS_NewImageManager(nsIImageManager **aInstancePtrResult);
 

gfx/src/nsIImageObserver.h

@@ -27,8 +27,8 @@ class nsIImage;
 class nsIImageRequest;
 class nsIImageGroup;
 
+/// Image request notifications
 typedef enum {
-  // Image request notifications
   nsImageNotification_kStartURL,      // Start of decode/display for URL.
   nsImageNotification_kDescription,   // Availability of image description.
   nsImageNotification_kDimensions,    // Availability of image dimensions. 
@@ -51,6 +51,7 @@ typedef enum {
   nsImageNotification_kInternalImage, // Internal image icon.
 } nsImageNotification;
 
+/// Image group notifications
 typedef enum {
 
   // Start of image loading. Sent when  a loading image is 
@@ -75,6 +76,7 @@ typedef enum {
 
 } nsImageGroupNotification;
 
+/// Image loading errors
 typedef enum {
   nsImageError_kNotInCache,           // Image URL not available in cache when 
                                       // kOnlyFromCache flag was set.
@@ -98,40 +100,66 @@ typedef enum {
 { 0xb3cad300, 0xb8f4, 0x11d1,         \
 { 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
 
+/**
+ * Image request observer interface. The implementor will be notified
+ * of significant loading events or loading errors.
+ */
 class nsIImageRequestObserver : public nsISupports {
 public:
-  // Notify the observer of some significant image event. The parameter
+  /** 
-  // values depend on the notification type as specified below:
+   * Notify the observer of some significant image event. The parameter
-  //
+   * values depend on the notification type as specified below.
-  // kDescription - aParam3 is a string containing the human readable
+   *
-  //                description of an image, e.g. "GIF89a 320 x 240 pixels".  
+   * kDescription - aParam3 is a string containing the human readable
-  //                The string storage is static, so it must be copied if
+   *                description of an image, e.g. "GIF89a 320 x 240 pixels".  
-  //                it is to be preserved after the call to the observer. 
+   *                The string storage is static, so it must be copied if
-  // kDimensions - aParam1 and aParam2 are the width and height respectively
+   *                it is to be preserved after the call to the observer. 
-  //               of the image.
+   * kDimensions - aParam1 and aParam2 are the width and height respectively
-  // kPixmapUpdate - aParame3 is a pointer to a nsRect struct containing the
+   *               of the image.
-  //                 rectangular area of pixels which has been modified by 
+   * kPixmapUpdate - aParame3 is a pointer to a nsRect struct containing the
-  //                 the image library.  This notification enables the 
+   *                 rectangular area of pixels which has been modified by 
-  //                 client to drive the progressive display of the image.
+   *                 the image library.  This notification enables the 
-  // kProgress - aParam1 represents the estimated percentage decoded.  This
+   *                 client to drive the progressive display of the image.
-  //             notification occurs at unspecified intervals.  Provided 
+   * kProgress - aParam1 represents the estimated percentage decoded.  This
-  //             that decoding proceeds without error, it is guaranteed that
+   *             notification occurs at unspecified intervals.  Provided 
-  //             notification will take place on completion with a 
+   *             that decoding proceeds without error, it is guaranteed that
-  //             percent_progress value of 100.
+   *             notification will take place on completion with a 
-  //
+   *             percent_progress value of 100.
+   *
+   * @param aImageRequest - the image request in question
+   * @param aImage - the corresponding image object
+   * @param aNotificationType - the type of notification
+   * @param aParam1, aParam2, aParam3 - additional information as described
+   *       above.
+   */
   virtual void Notify(nsIImageRequest *aImageRequest,
                       nsIImage *aImage,
                       nsImageNotification aNotificationType,
                       PRInt32 aParam1, PRInt32 aParam2,
                       void *aParam3)=0;
 
-  // Notify the observer of an error during image loading.
+  /**
+   *  Notify the observer of an error during image loading.
+   *
+   *  @param aImageRequest - the image request in question
+   *  @param aErrorType - the error code
+   */
   virtual void NotifyError(nsIImageRequest *aImageRequest,
                            nsImageError aErrorType)=0;
 };
 
+/**
+ * Image group observer interface. The implementor will be notified
+ * of significant image group events.
+ */
 class nsIImageGroupObserver : public nsISupports {
 public:
+  /**
+   *  Notify the observer of some significant image group event.
+   *
+   *  @param aImageGroup - the image group in question
+   *  @param aNotificationType - the notification code
+   */
   virtual void Notify(nsIImageGroup *aImageGroup,
                       nsImageGroupNotification aNotificationType)=0;
 };

gfx/src/nsIImageRequest.h

@@ -31,24 +31,43 @@ class nsIImage;
 { 0xc31444c0, 0xaec9, 0x11d1,  \
 { 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
 
+/**
+ *
+ * An image request generated as a result of invoking the 
+ * <code>GetImage</code> method of the <code>nsIImageGroup</code>
+ * interface. 
+ */
 class nsIImageRequest : public nsISupports {
 public:  
-  // Get the image associated with the request.
+  /// @return the image object associated with the request.
   virtual nsIImage* GetImage() = 0;
   
-  // Return the natural dimensions of the image.  Returns 0,0 
+  /**
-  //if the dimensions are unknown.
+   *  Returns the natural dimensions of the image.  Returns 0,0 
+   *  if the dimensions are unknown.
+   * 
+   * @param aWidth, aHeight - pointers to integers to be filled in with
+   *      the dimensions.
+   */
   virtual void GetNaturalDimensions(PRUint32 *aWidth, PRUint32 *aHeight) = 0;
-
+ 
-  // Add and remove observers to listen in on image loading notifications
+  /** 
+   * Add an observers to be informed of image loading notifications.
+   *
+   * @param aObserver - An observer to add to the observer list.
+   * @param boolean indicating whether addition was successful.
+   */
   virtual PRBool AddObserver(nsIImageRequestObserver *aObserver) = 0;
+
+  /**
+   * Remove a previously added observer from the observer list.
+   *
+   * @param aObserver - An observer to remove from the observer list.
+   * @param boolean indicating whether the removal was successful.
+   */ 
   virtual PRBool RemoveObserver(nsIImageRequestObserver *aObserver) = 0;
 
-  // Interrupt loading of just this image.
+  /// Interrupt loading of just this image.
   virtual void Interrupt() = 0;
 };
-
-extern NS_GFX nsresult
-  NS_NewImageRequest(nsIImageRequest **aInstancePtrResult);                   
-
 #endif