Ticket #13426: MPIndex.h.diff

MPIndex.h

@@ -33 +33 @@
  *      POSSIBILITY OF SUCH DAMAGE.
  */
 
+/*!
+ @header
+ The MPIndex maintains an in-memory cache of all available ports and their 
+ install status.
+*/
 #import <Cocoa/Cocoa.h>
 #import "MPMacPorts.h"
 #import "MPPort.h"
@@ -40 +45 @@
 #define MPIndexWillSetIndex     @"org.macports.framework.index.willSetIndex"
 #define MPIndexDidSetIndex      @"org.macports.framework.index.didSetIndex"
 
+/*!
+ @class MPIndex
+ @abstract Index of all ports
+ @discussion Maintains an in-memory cache of all available ports and their 
+ install status. The MPIndex class is analogous to the PortIndex files for every 
+ port collection (most users have just one collection listed in 
+ /opt/local/etc/macports/sources.conf).
+ */
 @interface MPIndex : MPMutableDictionary {
 
 }
 
+/*!
+ @brief Initialize a newly allocated index with enough memory for numItems ports
+ @param numItems The number of ports that the index will initially have capacity for
+ */
+- (id)initWithCapacity:(unsigned)numItems;
+
+/*!
+ @brief Returns a new array conaining of all available ports
+ */
 - (NSArray *)ports;
+
+/*!
+@brief Returns a new array of all port names
+ */
 - (NSArray *)portNames;
 
+/*!
+@brief Loads all ports into the index from the MacPorts backend
+*/
 - (void)setIndex;
 
+/*!
+@brief Returns the port with the given name
+@param name The name of the port
+ */
 - (MPPort *)port:(NSString *)name;
+
+/*!
+@brief Returns an enumerator of all ports
+ */
 - (NSEnumerator *)portEnumerator;
+
+/*!
+ @brief Removes the port with the given name from the index
+ @param name The name of the port
+ */
 - (void)removePort:(NSString *)name;
+
+/*!
+@brief Adds the port to the index
+ @param port The port
+@discussion The default state for the port is "not installed"
+ */
 - (void)setPort:(MPPort *)port;
 
 + (Class)classForKeyedUnarchiver;