[31523] users/rhwood/MacPorts.Framework

[rhwood at macports.org]

Revision: 31523
          http://trac.macosforge.org/projects/macports/changeset/31523
Author:   rhwood at macports.org
Date:     2007-11-27 01:56:06 -0800 (Tue, 27 Nov 2007)

Log Message:
-----------
Add documentation by Kirk Kelsey from ticket:13426

Modified Paths:
--------------
    users/rhwood/MacPorts.Framework/MPIndex.h
    users/rhwood/MacPorts.Framework/MPRegistry.h

Modified: users/rhwood/MacPorts.Framework/MPIndex.h
===================================================================
--- users/rhwood/MacPorts.Framework/MPIndex.h	2007-11-27 06:18:20 UTC (rev 31522)
+++ users/rhwood/MacPorts.Framework/MPIndex.h	2007-11-27 09:56:06 UTC (rev 31523)
@@ -33,6 +33,11 @@
  *	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,18 +45,61 @@
 #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;
+
+/*!
+ at brief Returns a new array of all port names
+ */
 - (NSArray *)portNames;
 
+/*!
+ at brief Loads all ports into the index from the MacPorts backend
+*/
 - (void)setIndex;
 
+/*!
+ at brief Returns the port with the given name
+ at param name The name of the port
+ */
 - (MPPort *)port:(NSString *)name;
+
+/*!
+ at 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;
+
+/*!
+ at brief Adds the port to the index
+ @param port The port
+ at discussion The default state for the port is "not installed"
+ */
 - (void)setPort:(MPPort *)port;
 
 + (Class)classForKeyedUnarchiver;

Modified: users/rhwood/MacPorts.Framework/MPRegistry.h
===================================================================
--- users/rhwood/MacPorts.Framework/MPRegistry.h	2007-11-27 06:18:20 UTC (rev 31522)
+++ users/rhwood/MacPorts.Framework/MPRegistry.h	2007-11-27 09:56:06 UTC (rev 31523)
@@ -33,11 +33,21 @@
  *	POSSIBILITY OF SUCH DAMAGE.
  */
 
+/*!
+ @header
+ MPRegistry provides a programatic interface to the registry of installed ports.
+ The MPRegistry class is a wrapper around the Tcl Registry API. For interacting 
+ with all available ports, see the @link MPIndex MPIndex @/link.
+ */
 #import <Cocoa/Cocoa.h>
 #import "MPInterpreter.h"
 #import "MPPort.h"
 #import "MPReceipt.h"
 
+/*!
+ @class MPRegistry
+ @abstract The registry of installed ports.
+  */
 @interface MPRegistry : NSObject {
 
 	MPInterpreter *interpreter;
@@ -47,23 +57,28 @@
 + (MPRegistry *)sharedRegistry;
 
 /*
- * Call [self installed:@""]
+ @brief Calls [self installed:@""]
  */
 - (NSDictionary *)installed;
 /*
- * Call [self installed:name version:@""]
+ @brief Calls [self installed:name version:@""]
+ @param name Text to match the port name
  */
 - (NSDictionary *)installed:(NSString *)name;
-/*
- * Returns a NSDictionary of MPReciepts keyed by port name
+/*!
+ @brief Returns an NSDictionary of MPReciepts keyed by port name
+ @param name Text to match the port name
+ @param version Text to match the port version
  */
 - (NSDictionary *)installed:(NSString *)name withVersion:(NSString *)version;
-/*
- * Return an array of installed port names
+/*!
+ @brief Returns an array of installed port names
+ @param name Text to match the port name
+ @param version Text to march the port version
  */
 - (NSArray *)installedAsArray:(NSString *)name withVersion:(NSString *)version;
-/*
- * Return an array of the files in the (installed and active) port
+/*!
+ @brief Returns an array of the files in the (installed and active) port
  */
 - (NSArray *)filesForPort:(NSString *)name;
 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20071127/ced8d1d1/attachment.html