Commits

Tuukka Norri committed 74abb2d

Added \brief tags to documentation
JAVADOC_AUTOBRIEF didn't work correctly.

Comments (0)

Files changed (39)

 # comments will behave just like regular Qt-style comments 
 # (thus requiring an explicit @brief command for a brief description.)
 
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will 
 # interpret the first line (until the first dot) of a Qt-style 

Sources/BXAbstractDescription.m

 
 
 /**
- * An abstract superclass for various description classes.
+ * \brief An abstract superclass for various description classes.
  * \ingroup descriptions
  */
 @implementation BXAbstractDescription
 }
 
 
-/** Name of the object. */
+/** \brief Name of the object. */
 - (NSString *) name
 {
     return [[mName retain] autorelease];

Sources/BXArrayProxy.m

 
 
 /**
- * An NSArray or NSMutableArray-style self-updating container proxy.
+ * \brief An NSArray or NSMutableArray-style self-updating container proxy.
  * \ingroup auto_containers
  */
 @implementation BXArrayProxy

Sources/BXAttributeDescription.m

 
 
 /**
- * An attribute description contains information about a column in a specific entity.
+ * \brief An attribute description contains information about a column in a specific entity.
  * \ingroup descriptions
  */
 @implementation BXAttributeDescription
 	[super encodeWithCoder: coder];
 }
 
-/** Whether the attribute is part of the primary key of its entity. */
+/** \brief Whether the attribute is part of the primary key of its entity. */
 - (BOOL) isPrimaryKey
 {
 	return (mFlags & kBXPropertyPrimaryKey ? YES : NO);
 }
 
 /** 
- * Whether the attribute will be excluded from fetches and queried only when needed. 
+ * \brief Whether the attribute will be excluded from fetches and queried only when needed. 
  * \see BXDatabaseContext::executeFetchForEntity:withPredicate:excludingFields:error:
  */
 - (BOOL) isExcluded
 	return (mFlags & kBXPropertyExcluded ? YES : NO);
 }
 
-/** Name of the attribute's database type. */
+/** \brief Name of the attribute's database type. */
 - (NSString *) databaseTypeName
 {
 	return mDatabaseTypeName;
 }
 
-/** Class of fetched objects. */
+/** \brief Class of fetched objects. */
 - (Class) attributeValueClass
 {
 	return mAttributeClass;
 }
 
-/** Class name of fetched values. */
+/** \brief Class name of fetched values. */
 - (NSString *) attributeValueClassName
 {
 	return NSStringFromClass (mAttributeClass);
 //@{
 /**
  * \internal
- * Create an attribute description.
+ * \brief Create an attribute description.
  * \param       aName       Name of the attribute
  * \param       anEntity    The entity which contains the attribute.
  * \return                  The attribute description.

Sources/BXConstantsPrivate.h

 
 /**
  * \internal
- * Notifications for self-updating containers to be sent before the others.
+ * \brief Notifications for self-updating containers to be sent before the others.
  */
 //@{
 BX_EXPORT NSString* const kBXInsertEarlyNotification;

Sources/BXContainerProxy.m

 
 
 /**
- * A generic self-updating container proxy.
+ * \brief A generic self-updating container proxy.
  * \ingroup auto_containers
  */
 @implementation BXContainerProxy
 
 @implementation BXContainerProxy (Accessors)
 
-/** The container's context. */
+/** \brief The container's context. */
 - (BXDatabaseContext *) context
 {
     return mContext; 
     }
 }
 
-/** The container's filter predicate. */
+/** \brief The container's filter predicate. */
 - (NSPredicate *) filterPredicate;
 {
     return mFilterPredicate;
     }
 }
 
-/** The container's owner. */
+/** \brief The container's owner. */
 - (id) owner
 {
 	return mOwner;
 }
 
 /** 
- * Set the cotainer's owner.
+ * \brief Set the cotainer's owner.
+ *
  * NSKeyValueObserving notifications will be posted to the owner.
  * \note The owner is not retained.
  */
     mOwner = anObject;
 }
 
-/** The owner's key for the container. */
+/** \brief The owner's key for the container. */
 - (NSString *) key
 {
     return [[mKey copy] autorelease];
 }
 
 /** 
- * Set the owner's key for the container.
+ * \brief Set the owner's key for the container.
+ *
  * NSKeyValueObserving notifications will be posted using this key.
  */
 - (void) setKey: (NSString *) aString

Sources/BXDatabaseContext.h

 	id <BXDatabaseContextDelegate>			mDelegateProxy;
 	NSError*								mLastConnectionError;
 	
-	/** An NSWindow to which sheets are attached. \see -modalWindow */
+	/** \brief An NSWindow to which sheets are attached. \see -modalWindow */
 	IBOutlet NSWindow*						modalWindow;
 	IBOutlet id	<BXDatabaseContextDelegate>	delegate;
 	

Sources/BXDatabaseContext.m

 
 
 /** 
- * The database context. 
+ * \brief The database context. 
+ *
  * A database context connects to a given database, sends queries and commands to it and
  * creates objects from rows in its tables. In order to function properly, it needs an URI formatted 
  * like pgsql://username:password\@hostname/database_name/.
 /** \name Creating a database context */
 //@{
 /**
- * A convenience method.
+ * \brief A convenience method.
  * \param   uri     URI of the target database
  * \return          The database context
  * \throw   NSException named \c kBXUnsupportedDatabaseException in case the given URI cannot be handled.
 }
 
 /**
- * An initializer.
+ * \brief An initializer.
+ *
  * The database URI has to be set afterwards.
  * \return          The database context
  */
 }
 
 /**
- * The designated initializer.
+ * \brief The designated initializer.
  * \param   uri     URI of the target database
  * \return          The database context
  * \throw           NSException named \c kBXUnsupportedDatabaseException in case the given URI cannot be handled.
 }
 
 /**
- * Set whether the receiver should retain all registered objects.
+ * \brief Set whether the receiver should retain all registered objects.
  */
 - (void) setRetainsRegisteredObjects: (BOOL) flag
 {
 /** \name Connecting and disconnecting */
 //@{
 /**
- * Set the database URI.
+ * \brief Set the database URI.
+ *
  * Also clears the context's strong references to entity descriptions received from it.
  * \param   uri     The database URI
  * \throw   NSException named \c kBXUnsupportedDatabaseException in case the given URI cannot be handled.
 }
 
 /**
- * The database URI.
+ * \brief The database URI.
  */
 - (NSURL *) databaseURI
 {
 }
 
 /**
- * Whether connection is attempted on -awakeFromNib.
+ * \brief Whether connection is attempted on -awakeFromNib.
  */
 - (BOOL) connectsOnAwake
 {
 }
 
 /**
- * Set whether connection should be attempted on -awakeFromNib.
+ * \brief Set whether connection should be attempted on -awakeFromNib.
  */
 - (void) setConnectsOnAwake: (BOOL) aBool
 {
 }
 
 /**
- * Establishing a connection.
+ * \brief Establishing a connection.
+ *
  * Returns a boolean indicating whether connecting can be attempted using -connect:.
  * Presently this method returns YES when connection attempt hasn't already been started and after
  * the attempt has failed.
 }
 
 /**
- * Connection status.
+ * \brief Connection status.
  */
 - (BOOL) isConnected
 {
 }
 
 /**
- * Connect to the database.
+ * \brief Connect to the database.
+ *
  * This method returns after the connection has been made.
  */
 - (BOOL) connectSync: (NSError **) error
 }
 
 /**
- * Connect to the database.
+ * \brief Connect to the database.
+ *
  * Hand over the connection setup to \c mConnectionSetupManager. In BaseTenAppKit 
  * applications, a BXNetServiceConnector will be created automatically if 
  * one doesn't exist.
 }
 
 /**
- * Connect to the database.
+ * \brief Connect to the database.
+ *
  * This method returns immediately.
  * After the attempt, either a \c kBXConnectionSuccessfulNotification or a 
  * \c kBXConnectionFailedNotification will be posted to the context's
 }
 
 /**
- * Disconnect from the database.
+ * \brief Disconnect from the database.
  */
 - (void) disconnect
 {
 /** \name Transactions and undo */
 //@{
 /**
- * Set the query execution method.
+ * \brief Set the query execution method.
+ *
  * In manual commit mode, savepoints are inserted after each query
  * Changes don't get propagated immediately to other clients.
  * Instead, other users get information about locked rows.
 }
 
 /**
- * Query execution method
+ * \brief Query execution method
  * \return          A BOOL indicating whether or not autocommit is in use.
  */
 - (BOOL) autocommits
 }
 
 /**
- * Set whether the context should try to lock rows before editing.
+ * \brief Set whether the context should try to lock rows before editing.
+ *
  * BaseTen's controller subclasses notify the context in NSEditorRegistration's methods.
  * This method controls whether the context pays attention to those messages.
  * The context may still receive lock notifications from other contexts.
 }
 
 /**
- * Whether the context tries to lock rows before editing.
+ * \brief Whether the context tries to lock rows before editing.
  */
 - (BOOL) sendsLockQueries
 {
 }
 
 /**
- * The undo manager used by this context.
+ * \brief The undo manager used by this context.
  */
 - (NSUndoManager *) undoManager
 {
 }
 
 /**
- * Set the undo manager used by the context.
+ * \brief Set the undo manager used by the context.
+ *
  * Instead of creating an undo manager owned by the context, the undo invocations 
  * can be sent to a window's undo manager, for example. The change is done only if there isn't an
  * open undo group in the current undo manager.
 }
 
 /**
- * Rollback the transaction ina manual commit mode.
+ * \brief Rollback the transaction ina manual commit mode.
+ *
  * Guaranteed to succeed.
  */
 - (void) rollback
 }
 
 /**
- * Commit the current transaction in manual commit mode.
+ * \brief Commit the current transaction in manual commit mode.
+ *
  * Undo will be disabled after this.
  * \return      A boolean indicating whether the commit was successful or not.
  */
 }
 
 /** 
- * Commit the changes.
+ * \brief Commit the changes.
  * \param sender Ignored.
  * \throw A BXException named \c kBXFailedToExecuteQueryException if commit fails.
  */
 }
 
 /**
- * Rollback the changes.
+ * \brief Rollback the changes.
  * \param sender Ignored.
  */
 - (IBAction) revertDocumentToSaved: (id) sender
  */
 //@{
 /**
- * Objects with given IDs.
+ * \brief Objects with given IDs.
+ *
  * If the objects do not exist yet, they get created.
  * The database is not queried in any case. It is the user's responsibility to
  * provide this method with valid IDs.
 }
 
 /**
- * Retrieve a registered database object.
+ * \brief Retrieve a registered database object.
+ *
  * Looks up an object from the cache. The database is not queried in any case.
  * \return The cached object or nil.
  */
 }
 
 /**
- * Retrieve registered database objects.
+ * \brief Retrieve registered database objects.
+ *
  * Looks up objects from the cache. The database is not queried in any case.
  * \param objectIDs         The object IDs to look for.
  * \return An NSArray of cached objects and NSNulls.
 }
 
 /**
- * Retrieve registered database objects.
+ * \brief Retrieve registered database objects.
+ *
  * Looks up objects from the cache. The database is not queried in any case.
  * \param objectIDs         The object IDs to look for.
  * \param returnNullObjects Whether the returned array should be filled with NSNulls
 
 
 /** 
- * The delegate. 
+ * \brief The delegate. 
  */
 - (id <BXDatabaseContextDelegate>) delegate
 {
 }
 
 /**
- * Set the delegate.
+ * \brief Set the delegate.
+ *
  * The delegate object will not be retained.
  */
 - (void) setDelegate: (id <BXDatabaseContextDelegate>) anObject;
 /** \name Using the Keychain */
 //@{
 /**
- * Whether the default keychain is searched for database passwords.
+ * \brief Whether the default keychain is searched for database passwords.
  */
 - (BOOL) usesKeychain
 {
 }
 
 /**
- * Set whether the default keychain should be searched for database passwords.
+ * \brief Set whether the default keychain should be searched for database passwords.
  */
 - (void) setUsesKeychain: (BOOL) usesKeychain
 {
 }
 
 /**
- * Store login credentials from the database URI to the default keychain.
+ * \brief Store login credentials from the database URI to the default keychain.
  */
 - (void) storeURICredentials
 {
 /** \name Faulting database objects */
 //@{
 /**
- * Refresh or fault an object.
+ * \brief Refresh or fault an object.
+ *
  * This method is provided for Core Data compatibility.
  * \param flag   If NO, all the object's cached values including related objects will be released.
  *               A new fetch won't be performed until any of the object's values is requested.
 /** \name Receiving notifications */
 //@{
 /**
- * The notification center for this context.
+ * \brief The notification center for this context.
+ *
  * Context-related notifications, such as connection notifications,
  * are posted to this notification center instead of the default center.
  */
 
 /** \name Error handling */
 //@{
-/** The NSWindow used with various sheets. */
+/** \brief The NSWindow used with various sheets. */
 - (NSWindow *) modalWindow
 {
 	return modalWindow;
 }
 
 /**
- * Set the NSWindow used with various sheets.
+ * \brief Set the NSWindow used with various sheets.
+ *
  * If set to nil, application modal alerts will be used.
  */
 - (void) setModalWindow: (NSWindow *) aWindow
 
 /** 
  * \name Retrieving objects from the database
- * These methods block until the result has been retrieved.
+ * \brief These methods block until the result has been retrieved.
  */
 //@{
 /**
- * Fetch an object with a given ID.
+ * \brief Fetch an object with a given ID.
+ *
  * The database is queried only if the object isn't in cache.
  */
 - (id) objectWithID: (BXDatabaseObjectID *) anID error: (NSError **) error
 }
 
 /**
- * Fetch objects with given IDs.
+ * \brief Fetch objects with given IDs.
+ *
  * The database is queried only if the object aren't in cache.
  */
 - (NSSet *) objectsWithIDs: (NSArray *) anArray error: (NSError **) error
 }
 
 /**
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
+ *
  * Essentially calls #executeFetchForEntity:withPredicate:returningFaults:error: with \c returningFaults set to NO.
  *  
  * \param       entity          The entity from which rows are fetched.
 }
 
 /**
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
+ *
  * Instead of fetching the field values, the context can retrieve objects that
  * contain only the object ID. The other values get fetched on-demand.\n
  * Essentially calls #executeFetchForEntity:withPredicate:returningFaults:updateAutomatically:error: with \c updateAutomatically set to NO.
 }
 
 /**
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
+ *
  * Instead of fetching all the columns, the user may supply a list of fields
  * that are excluded from the query results. The returned objects are 
  * faults. Values for the non-excluded fields are cached, though.\n
 }
 
 /** 
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
+ *
  * The result array can be set to be updated automatically. 
  * \param       entity          The entity from which rows are fetched.
  * \param       predicate       A WHERE clause is constructed using this predicate. May be nil.
 }
 
 /**
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
+ *
  * The result array can be set to be updated automatically.
  * \param       entity          The entity from which rows are fetched.
  * \param       predicate       A WHERE clause is constructed using this predicate. May be nil.
 /** \name Creating new database objects */
 //@{
 /**
- * Create a new database object.
+ * \brief Create a new database object.
+ *
  * Essentially inserts a new row into the database and retrieves it.
  * \param       entity           The target entity.
  * \param       givenFieldValues Initial values for fields. May be nil or left empty if
 /** \name Deleting database objects */
 //@{
 /**
- * Delete a database object.
+ * \brief Delete a database object.
+ *
  * Essentially this method deletes a single row from the database.
  * \param       anObject        The object to be deleted.
  * \param       error           If an error occurs, this pointer is set to an NSError instance.
 /** \name Executing arbitrary queries */
 //@{
 /**
- * Execute a query directly.
+ * \brief Execute a query directly.
+ *
  * This method should only be used when fetching objects and modifying 
  * them is cumbersome or doesn't accomplish the task altogether.
  * \return An NSArray of NSDictionaries that correspond to each row.
 }
 
 /**
- * Execute a query directly.
+ * \brief Execute a query directly.
+ *
  * This method should only be used when fetching objects and modifying 
  * them is cumbersome or doesn't accomplish the task altogether.
  * \param queryString The SQL query.
 }
 
 /**
- * Execute a command directly.
+ * \brief Execute a command directly.
+ *
  * This method should only be used when fetching objects and modifying 
  * them is cumbersome or doesn't accomplish the task altogether.
  * \return The number of rows affected by the command.
  */
 //@{
 /** 
- * Entity for a table in the given schema. 
+ * \brief Entity for a table in the given schema.
  * \note Entities are associated with a database URI. Thus the database context needs an URI containing a host and 
  *       the database name before entities may be received.
  */
 }
 
 /** 
- * Entity for a table in the default schema 
+ * \brief Entity for a table in the default schema 
  * \note Entities are associated with a database URI. Thus the database context needs an URI containing a host and 
  *       the database name before entities may be received.
  */
 }
 
 /**
- * All entities found in the database.
+ * \brief All entities found in the database.
+ *
  * Entities in private and metadata schemata won't be included.
  * \param reload Whether the entity list should be reloaded.
  * \param       error           If an error occurs, this pointer is set to an NSError instance.
 
 /** 
  * \internal
- * Delete multiple objects at the same time. 
+ * \brief Delete multiple objects at the same time. 
  * \note Redoing this re-executes the query with the given predicate and thus
  *       might cause other objects to be deleted than those which were in the original invocation.
  */
 
 /**
  * \internal
- * Fetch objects from the database.
+ * \brief Fetch objects from the database.
  * \param       returnedClass   The class an instance of which gets returned. The class should be a
  *                              subclass of BXContainerProxy.
  */
 //FIXME: do the following methods set modification types correctly in undo & redo, or do they get set in callbacks?
 /** 
  * \internal
- * Update multiple objects at the same time. 
+ * \brief Update multiple objects at the same time. 
  * \note Redoing this re-executes the query with the given predicate and thus
  *       might cause modifications in other objects than in the original invocation.
  */
 
 /**
  * \internal
- * Register an object to the context
+ * \brief Register an object to the context.
+ *
  * After fetching objects from the database, a database interface should register them with a context.
  * This enables updating the database as well as automatic synchronization, if this has been implemented
  * in the database interface class.

Sources/BXDatabaseObject.m

 }
 
 /**
- * Is the given selector a setter or a getter?
+ * \brief Is the given selector a setter or a getter?
  * \return 2 if setter, 1 if getter, 0 if neither
  */
 static int 
 }    
 
 /** 
- * A class that represents a single row in a database table.
+ * \brief A class that represents a single row in a database table.
+ *
  * The objects returned by the database context are instances of this class 
  * or its subclasses. The class is KVC-compliant. It is not thread-safe
  * for the most part, i.e. if methods of an BXDatabaseObject instance will 
 }
 
 /** 
- * The database context to which this object is registered. 
+ * \brief The database context to which this object is registered. 
+ *
  * This method doesn't cause a fault to fire.
  */
 - (BXDatabaseContext *) databaseContext
 }
 
 /**
- * Test object equality.
+ * \brief Test object equality.
+ *
  * Currently objects are considered equal if they are managed by the same database context and
  * their object IDs are equal.
  * This method doesn't cause a fault to fire.
 }
 
 /** 
- * A convenience method for retrieving values for multiple keys. 
+ * \brief A convenience method for retrieving values for multiple keys. 
  * \param   keys    An NSArray of NSStrings.
  * \return          The requested values.
  */
 }
 
 /**
- * Value or objects from the database.
+ * \brief Value or objects from the database.
+ *
  * Look up the value from cache or ask the database context to fetch it.
  * Currently this method calls #primitiveValueForKey:.
  * \param   aKey    A BXAttributeDescription.
 }
 
 /** 
- * A convenience method for retrieving values for multiple keys. 
+ * \brief A convenience method for retrieving values for multiple keys. 
  * \param   keys    An NSArray of BXAttributeDescriptions.
  * \return          The requested values.
  */
 }
 
 /**
- * Validate a value.
+ * \brief Validate a value.
+ *
  * Currently, only null constraints are checked.
  * This method doesn't cause a fault to fire.
  */
 }
 
 /**
- * Determines whether the receiver can be deleted in its current state.
+ * \brief Determines whether the receiver can be deleted in its current state.
+ *
  * Currently, only inverse relationships' delete rules are checked.
  * This method could cause a fault to fire.
  */
 }
 
 /** 
- * The object ID. 
+ * \brief The object ID. 
+ *
  * This method doesn't cause a fault to fire.
  */
 - (BXDatabaseObjectID *) objectID
 }
 
 /**
- * Predicate for this object.
+ * \brief Predicate for this object.
+ *
  * This method might cause a fault to fire.
  */
 - (NSPredicate *) predicate
 
 /**
  * \internal
- * Returns cached objects.
+ * \brief Returns cached objects.
  */
 - (NSDictionary *) cachedObjects
 {
 }
 
 /**
- * A proxy for monitoring the object's status.
+ * \brief A proxy for monitoring the object's status.
+ *
  * Returns a proxy that can be used with BXObjectStatusToEditableTransformer and
  * BXObjectStatusToColorTransformer.
  * This method doesn't cause a fault to fire.
 }
 
 /**
- * Value from the object's cache.
+ * \brief Value from the object's cache.
+ *
  * This method is thread-safe and doesn't cause a fault to fire.
  * \return      The value in question or nil, if it has not been fetched from the database yet.
  *              NSNulls represent nil values.
 }
 
 /**
- * Value or objects from the database.
+ * \brief Value or objects from the database.
+ *
  * Look up the value from cache or ask the database context to fetch it.
  * Calls super's implementation of -valueForUndefinedKey: if the key isn't known.
  * \param   aKey    Name of the column or a relationship.
 }
 
 /** 
- * Set value for a given key in the database.
+ * \brief Set value for a given key in the database.
  * \param   aVal    The new value. May be nil for ordinary columns.
  * \param   aKey    An NSString.
  */
 }
 
 /**
- * Set multiple values.
+ * \brief Set multiple values.
+ *
  * This is not merely a convenience method; invoking this is potentially much faster than 
  * repeatedly using #setPrimitiveValue:forKey:. However, for foreign keys, #setPrimitiveValue:forKey: 
  * should be used instead or the collection proxy be modified directly.
 }
 
 /** 
- * Fault the given key. 
+ * \brief Fault the given key. 
+ *
  * The object's cached value or related object will be released.
  * A new fetch won't be performed until any of the object's values is requested.
  * \param aKey The key to fault. If nil, all values will be removed.
 }
 
 /** 
- * Whether the given key is faulted or not.
+ * \brief Whether the given key is faulted or not.
+ *
  * This method doesn't cause a fault to fire.
  * \param   aKey    An NSString. May be nil, in which case the object
  *                  is considered a fault if value for any of its keys is
 }
 
 /**
- * Values from the object's cache.
+ * \brief Values from the object's cache.
+ *
  * This method is thread-safe and doesn't cause a fault to fire.
  * \return      An NSDictionary which contains the cached values.
  */
 }
 
 /**
- * Whether the given key is locked locked or not.
+ * \brief Whether the given key is locked locked or not.
+ *
  * Returns YES if modifying the given key would block.
  * Current implementation locks the whole object
  * when any key gets locked.
 }
 
 /**
- * Whether the object has beed deleted or is going to be deleted in the next commit.
+ * \brief Whether the object has beed deleted or is going to be deleted in the next commit.
+ *
  * This method doesn't cause a fault to fire.
  */
 - (BOOL) isDeleted
 
 //FIXME: documentation bug? This method's behaviour should be checked with Core Data.
 /**
- * Whether the object has been inserted to the database in a previous transaction.
+ * \brief Whether the object has been inserted to the database in a previous transaction.
+ *
  * If the object has been deleted, this method returns YES.
  * This method doesn't cause a fault to fire.
  */
 	return (kBXObjectExists != mDeleted || mCreatedInCurrentTransaction);
 }
 
-/** Retain on copy. */
+/** \brief Retain on copy. */
 - (id) copyWithZone: (NSZone *) zone
 {
 	return [self retain];
 }
 
-/** Returns the entity of the receiver. */
+/** \brief Returns the entity of the receiver. */
 - (BXEntityDescription *) entity
 {
 	return [[self objectID] entity];
 @implementation BXDatabaseObject (Subclassing)
 /**
  * \name Methods that subclasses might override
- * \brief
  * \note When fetching values, #primitiveValueForKey: will always be used.
  */
 //@{
 //
 /**
- * Callback for deserializing the row.
+ * \brief Callback for deserializing the row.
+ *
  * Called once after a fetch or firing a fault.
  */
 - (void) awakeFromFetch
 }
 
 /**
- * Callback for inserting the row into the database.
+ * \brief Callback for inserting the row into the database.
  * \note This method will be called before posting insert notifications
  *       and adding the object to self-updating collections.
  * \note BXDatabaseContext may create new objects during redo causing their 
 }
 
 /**
- * Callback for turning into a fault.
+ * \brief Callback for turning into a fault.
+ *
  * This method will be called if any of the object's fields is faulted.
  */
 - (void) didTurnIntoFault
 {
 }
 
-/** The designated initializer */
+/** \brief The designated initializer */
 - (id) init
 {
     if ((self = [super init]))
 }
 //@}
 
-/** Returns NO. */
+/** \brief Returns NO. */
 + (BOOL) accessInstanceVariablesDirectly
 {
     return NO;
 }
 
-/** Returns NO. */
+/** \brief Returns NO. */
 + (BOOL) automaticallyNotifiesObserversForKey: (NSString *) aKey
 {
 	return NO;
 
 /**
  * \internal
- * Register the object with a context.
+ * \brief Register the object with a context.
+ *
  * In order to function properly, the database object needs to know about its context and its entity.
  * Registration is possible only if the object has not already been assigned a context. 
  * \return A boolean indicating whether the operation was successful or not.
 
 /**
  * \internal
- * Register the object with a context.
+ * \brief Register the object with a context.
+ *
  * Register with a pre-defined object ID
  * \return A boolean indicating whether the operation was successful or not.
  */
 
 /**
  * \internal
- * Set lock status for the given key.
+ * \brief Set lock status for the given key.
  */
 - (void) setLockedForKey: (NSString *) aKey
 {
 
 /** 
  * \internal
- * A convenience method for handling the object's cache.
+ * \brief A convenience method for handling the object's cache.
  */
 - (void) setCachedValuesForKeysWithDictionary: (NSDictionary *) aDict
 {
 
 /**
  * \internal
- * Lock the object in an asynchronous manner.
+ * \brief Lock the object in an asynchronous manner.
+ *
  * Ask the database to change the status of the key. The result is sent to the 
  * provided object.
  * \param   key             The key to be locked

Sources/BXDatabaseObjectID.m

 
 
 /**
- * A unique identifier for a database object.
+ * \brief A unique identifier for a database object.
+ *
  * This class is not thread-safe, i.e. 
  * if methods of a BXDatabaseObjectID instance will be called from 
  * different threads the result is undefined.
 }
 
 /** 
- * Create an object identifier from an NSURL.
+ * \brief Create an object identifier from an NSURL.
  * \note This is not the designated initializer.
  */
 - (id) initWithURI: (NSURL *) anURI context: (BXDatabaseContext *) context error: (NSError **) error
     [super dealloc];
 }
 
-/** The entity of the receiver. */
+/** \brief The entity of the receiver. */
 - (BXEntityDescription *) entity
 {
     return mEntity;
 }
 
-/** URI representation of the receiver. */
+/** \brief URI representation of the receiver. */
 - (NSURL *) URIRepresentation
 {
     return mURIRepresentation;
 }
 
 /** 
- * An NSPredicate for this object ID.
+ * \brief An NSPredicate for this object ID.
  * The predicate can be used to fetch the object from the database, for example.
  */
 - (NSPredicate *) predicate
 
 
 @implementation BXDatabaseObjectID (NSCopying)
-/** Retain on copy. */
+/** \brief Retain on copy. */
 - (id) copyWithZone: (NSZone *) zone
 {
     return [self retain];
  * \internal
  * \name Creating object IDs */
 //@{
-/** A convenience method. */
+/** \brief A convenience method. */
 + (id) IDWithEntity: (BXEntityDescription *) aDesc primaryKeyFields: (NSDictionary *) pkeyFValues
 {
     NSArray* keys = [pkeyFValues allKeys];
 
 /** 
  * \internal
- * The designated initializer.
+ * \brief The designated initializer.
  */
 - (id) initWithEntity: (BXEntityDescription *) anEntity objectURI: (NSURL *) anURI
 {

Sources/BXManyToManyRelationshipDescription.m

 
 /** 
  * \internal
- * Deallocation helper. 
+ * \brief Deallocation helper. 
  */
 - (void) dealloc2
 {

Sources/BXObjectStatusInfo.m

 
 
 /**
- * A proxy for retrieving database object status.
+ * \brief A proxy for retrieving database object status.
  * \see ValueTransformers
  * \ingroup baseten
  */
 }
 
 /** 
- * Returns a status constant for the given key.
+ * \brief Returns a status constant for the given key.
+ *
  * The constant may then be passed to value transformers in BaseTenAppKit.
  * \param aKey An NSString that corresponds to a field name.
  * \return An NSValue that contains the constant.

Sources/BXPGInterface.m

 
 /**
  * \internal
- * A helper for determining returned attributes.
+ * \brief A helper for determining returned attributes.
+ *
  * Primary key attributes are always returned.
  */
 static int
 
 /**
  * \internal
- * Create a list of returned fields.
+ * \brief Create a list of returned fields.
+ *
  * This may be passed to SELECT or to a RETURNING clause.
  */
 static NSString*
 
 /**
  * \internal
- * Create a WHERE clause.
+ * \brief Create a WHERE clause.
  */
 static struct bx_predicate_st
 WhereClauseUsingEntity (BXPGQueryBuilder* queryBuilder, NSPredicate* predicate, BXEntityDescription* entity, PGTSConnection* connection)
 
 /**
  * \internal
- * Create a WHERE clause.
+ * \brief Create a WHERE clause.
  */
 static struct bx_predicate_st
 WhereClauseUsingObject (BXPGQueryBuilder* queryBuilder, NSPredicate* predicate, BXDatabaseObject* object)
 
 /**
  * \internal
- * Create a SELECT query.
+ * \brief Create a SELECT query.
  */
 static NSString*
 SelectQueryFormat (PGTSConnection* connection, BOOL forUpdate)
 
 /**
  * \internal
- * Create an NSArray from a PGTSResultSet.
+ * \brief Create an NSArray from a PGTSResultSet.
+ *
  * Objects that are already registered wont'be recreated.
  */
 static NSArray*
 
 /**
  * \internal
- * Create a database error.
+ * \brief Create a database error.
+ *
  * Automatically fills some common fields in the userInfo dictionary.
  */
 static NSError*
 
 /**
  * \internal
- * Create object IDs from a PGTSResultSet.
+ * \brief Create object IDs from a PGTSResultSet.
  * \param entity The IDs' entity.
  */
 static NSArray*
 
 
 /**
- * An error handler for ROLLBACK errors.
+ * \brief An error handler for ROLLBACK errors.
+ *
  * The intended use is to set a symbolic breakpoint for possible errors caught during ROLLBACK.
  */
 static void
 
 /** 
  * \internal
- * Lock an object asynchronously.
+ * \brief Lock an object asynchronously.
+ *
  * Lock notifications should always be listened to, since modifications cause the rows to be locked until
  * the end of the ongoing transaction.
  */
 
 /**
  * \internal
- * Unlock a locked object synchronously.
+ * \brief Unlock a locked object synchronously.
  */
 - (void) unlockObject: (BXDatabaseObject *) anObject key: (id) aKey
 {
 
 /**
  * \internal
- * Create an insert query.
+ * \brief Create an insert query.
  */
 - (NSString *) insertQuery: (BXEntityDescription *) entity fieldValues: (NSDictionary *) fieldValues error: (NSError **) error
 {

Sources/BXPGQueryBuilder.h

 
 /**
  * \internal
- * A facade for the predicate etc. handling classes.
+ * \brief A facade for the predicate etc. handling classes.
  */
 @interface BXPGQueryBuilder : NSObject 
 {

Sources/BXPGTransactionHandler.h

 
 /**
  * \internal
- * Begins a transaction.
+ * \brief Begins a transaction.
+ *
  * Begins a transactions unless there already is one.
  */
 - (BOOL) beginIfNeeded: (NSError **) outError;
 
 /**
  * \internal
- * Commits the current transaction.
+ * \brief Commits the current transaction.
  */
 - (BOOL) save: (NSError **) outError;
 
 /**
  * \internal
- * Cancels the current transaction.
+ * \brief Cancels the current transaction.
  */
 - (BOOL) rollback: (NSError **) outError;
 
 /**
  * \internal
- * Creates a savepoint if needed.
+ * \brief Creates a savepoint if needed.
+ *
  * Use with single queries.
  */
 - (BOOL) savepointIfNeeded: (NSError **) outError;
 
 /**
  * \internal
- * Rollback to last savepoint.
+ * \brief Rollback to last savepoint.
  */
 - (BOOL) rollbackToLastSavepoint: (NSError **) outError;
 
 /**
  * \internal
- * Creates a savepoint or begins a transaction.
+ * \brief Creates a savepoint or begins a transaction.
+ *
  * Use with multiple queries.
  */
 - (BOOL) beginSubTransactionIfNeeded: (NSError **) outError;
 
 /**
  * \internal
- * Commits a previously begun subtransaction.
+ * \brief Commits a previously begun subtransaction.
  */
 - (BOOL) endSubtransactionIfNeeded: (NSError **) outError;
 
 /**
  * \internal
- * Rollback a previously begun subtransaction.
+ * \brief Rollback a previously begun subtransaction.
  */
 - (void) rollbackSubtransaction;
 

Sources/BXPropertyDescription.m

 
 
 /**
- * A superclass for various description classes.
+ * \brief A superclass for various description classes.
  * \ingroup descriptions
  */
 @implementation BXPropertyDescription
 
 /**
  * \internal
- * Deallocation helper. 
+ * \brief Deallocation helper.
+ *
  * Subclasses should override this instead of dealloc and then call 
  * super's implementation of dealloc2. This is because BXPropertyDescriptions 
  * will be stored into a non-retaining collection on creation and removed from 
 {
 }
 
-/** Entity for this property. */
+/** \brief Entity for this property. */
 - (BXEntityDescription *) entity
 {
     return mEntity;
 }
 
-/** Retain on copy. */
+/** \brief Retain on copy. */
 - (id) copyWithZone: (NSZone *) zone
 {
     return [self retain];
     return rval;
 }
 
-/** Whether the property is optional. */
+/** \brief Whether the property is optional. */
 - (BOOL) isOptional
 {
 	return (mFlags & kBXPropertyOptional ? YES : NO);
 
 /**
  * \internal
- * The designated initializer.
+ * \brief The designated initializer.
  */
 - (id) initWithName: (NSString *) aName entity: (BXEntityDescription *) anEntity
 {

Sources/BXRelationshipDescription.m

 
 
 /**
- * A description for one-to-many relationships and a superclass for others.
+ * \brief A description for one-to-many relationships and a superclass for others.
+ *
  * Relationships between entities are defined with foreign keys in the database.
  * \note For this class to work in non-GC applications, the corresponding database context must be retained as well.
  * \ingroup descriptions
 
 /** 
  * \internal
- * Deallocation helper. 
+ * \brief Deallocation helper. 
  */
 - (void) dealloc2
 {
 }
 
 /**
- * Destination entity for this relationship.
+ * \brief Destination entity for this relationship.
  */
 - (BXEntityDescription *) destinationEntity
 {
 }
 
 /**
- * Inverse relationship for this relationship.
+ * \brief Inverse relationship for this relationship.
+ *
  * In BaseTen, inverse relationships always exist.
  */
 - (BXRelationshipDescription *) inverseRelationship
 }
 
 /**
- * Delete rule for this relationship.
+ * \brief Delete rule for this relationship.
  */
 - (NSDeleteRule) deleteRule
 {
 }
 
 /**
- * Whether this relationship is to-many.
+ * \brief Whether this relationship is to-many.
  */
 - (BOOL) isToMany
 {

Sources/BXSetHelperTableRelationProxy.m

 
 /**
  * \internal
- * An NSCountedSet-style self-updating container proxy for many-to-many relationships.
+ * \brief An NSCountedSet-style self-updating container proxy for many-to-many relationships.
  * \ingroup auto_containers
  */
 //FIXME: this needs to be changed to use set mutation -style KVO notifications.

Sources/BXSetProxy.m

 
 
 /**
- * An NSCountedSet-style self-updating container proxy.
+ * \brief An NSCountedSet-style self-updating container proxy.
  * \ingroup auto_containers
  */
 @implementation BXSetProxy

Sources/BXSetRelationProxy.m

 
 /**
  * \internal
- * An NSCountedSet-style self-updating container proxy for relationships.
+ * \brief An NSCountedSet-style self-updating container proxy for relationships.
  * \ingroup auto_containers
  */
 @implementation BXSetRelationProxy

Sources/PGTSAbstractClassDescription.m

 
 /** 
  * \internal
- * Abstract base class for database class objects.
+ * \brief Abstract base class for database class objects.
  */
 @implementation PGTSAbstractClassDescription
 

Sources/PGTSAbstractDescription.m

 
 /** 
  * \internal
- * Abstract base class
+ * \brief Abstract base class.
  */
 @implementation PGTSAbstractDescription
 
 }
 
 /**
- * Retain on copy.
+ * \internal
+ * \brief Retain on copy.
  */
 - (id) copyWithZone: (NSZone *) zone
 {

Sources/PGTSAdditions.h

 
 #if defined(__cplusplus)
 
-//FIXME: make some gc-compatible additions.
-
 namespace PGTS 
 {
 	struct ObjectHash

Sources/PGTSAdditions.m

 }
 
 /**
- * Escape the string for the SQL interpreter.
+ * \internal
+ * \brief Escape the string for the SQL interpreter.
  */
 - (NSString *) PGTSEscapedString: (PGTSConnection *) connection
 {
 }
 
 /**
- * The number of parameters in a string.
+ * \internal
+ * \brief The number of parameters in a string.
+ *
  * Parameters are marked as follows: $n. The number of parameters is equal to the highest value of n.
  */
 - (int) PGTSParameterCount
 
 @implementation NSNumber (PGTSAdditions)
 /**
- * Return the value as Oid.
+ * \internal
+ * \brief Return the value as Oid.
  * \sa PGTSOidAsObject
  */
 - (Oid) PGTSOidValue

Sources/PGTSCertificateVerificationDelegate.m

 
 /**
  * \internal
- * Default implementation for verifying OpenSSL X.509 certificates.
+ * \brief Default implementation for verifying OpenSSL X.509 certificates.
+ *
  * This class is thread-safe.
  */
 @implementation PGTSCertificateVerificationDelegate
 }
 
 /**
- * Get search policies.
- * To find search policies, we need to create
- * a search criteria. To create a search criteria, we need to give the criteria creation function some constants.
+ * \brief Get search policies.
+ *
+ * To find search policies, we need to create a search criteria. To create a search criteria, 
+ * we need to give the criteria creation function some constants.
  */
 - (NSArray *) policies
 {
 }
 
 /**
- * Create a SecCertificateRef from an OpenSSL certificate.
+ * \brief Create a SecCertificateRef from an OpenSSL certificate.
  * \param bioOutput A memory buffer so we don't have to allocate one.
  */
 - (SecCertificateRef) copyCertificateFromX509: (X509 *) opensslCert bioOutput: (BIO *) bioOutput
 }
 
 /**
- * Verify an OpenSSL X.509 certificate.
+ * \brief Verify an OpenSSL X.509 certificate.
+ *
  * Get the X.509 certificate from OpenSSL, encode it in DER format and let Security framework parse it again.
  * This way, we can use the Keychain to verify the certificate, since a CA trusted by the OS or the user
  * might have signed it or the user could have stored the certificate earlier. The preverification result
 }
 
 /**
- * Create a trust.
+ * \brief Create a trust.
+ *
  * To verify a certificate, we need to
  * create a trust. To create a trust, we need to find search policies.
  * \param certificates An array of SecCertificateRefs.
 }
 
 /**
- * Create Security certificates from OpenSSL certificates.
+ * \brief Create Security certificates from OpenSSL certificates.
  * \return An array of SecCertificateRefs.
  */
 - (CFArrayRef) copyCertificateArrayFromOpenSSLCertificates: (X509_STORE_CTX *) x509_ctx

Sources/PGTSCertificateVerificationDelegateProtocol.h

 
 @protocol PGTSCertificateVerificationDelegate
 /** 
- * Should the SSL connection be allowed or not.
+ * \internal
+ * \brief Should the SSL connection be allowed or not.
+ *
  * This might not be called from the main thread.
  */
 - (BOOL) PGTSAllowSSLForConnection: (PGTSConnection *) connection context: (void *) x509_ctx preverifyStatus: (int) preverifyStatus;

Sources/PGTSConnectionMonitor.m

 
 /**
  * \internal
- * A class cluster for handling various notifications provided by AppKit-specific classes.
+ * \brief A class cluster for handling various notifications provided by AppKit-specific classes.
+ *
  * This class and its subclasses are thread-safe.
  */
 @implementation PGTSConnectionMonitor

Sources/PGTSConnector.m

 
 /**
  * \internal
- * Verify an X.509 certificate.
+ * \brief Verify an X.509 certificate.
  */
 static int
 VerifySSLCertificate (int preverify_ok, X509_STORE_CTX *x509_ctx)

Sources/PGTSConstants.m

 NSString* const kPGTSSSLAttemptedKey			  = @"kPGTSSSLAttemptedKey";
 
 
-/** Declared in PGTSConnectionDelegate.h */
+/* Declared in PGTSConnectionDelegate.h */
 SEL kPGTSSentQuerySelector                  = NULL;
 SEL kPGTSFailedToSendQuerySelector          = NULL;
 SEL kPGTSAcceptCopyingDataSelector          = NULL;

Sources/PGTSDatabaseDescription.m

 
 /** 
  * \internal
- * Database.
+ * \brief Database.
  */
 @implementation PGTSDatabaseDescription
 

Sources/PGTSFieldDescription.m

 
 /** 
  * \internal
- * Table field.
+ * \brief Table field.
  */
 @implementation PGTSFieldDescription
 

Sources/PGTSFunctions.m

 
 
 /**
- * Return the value as an object
+ * \brief Return the value as an object.
  * \sa PGTSOidValue
  */
 id 

Sources/PGTSHOM.h

 - (id) PGTSSelectFunction: (int (*)(id, void*)) fptr argument: (void *) arg;
 /**
  * \internal
- * Visit each item.
+ * \brief Visit each item.
+ *
  * The first parameter after self and _cmd will be replaced with the visited object.
  * \param visitor The object that will be called.
  * \return An invocation recorder.

Sources/PGTSIndexDescription.m

 
 /** 
  * \internal
- * Table index
+ * \brief Table index
  */
 @implementation PGTSIndexDescription
 

Sources/PGTSResultSet.h

 
 
 @protocol PGTSResultRowProtocol <NSObject>
-/** Called when a new result set and row index are associated with the target */
+/** 
+ * \internal
+ * \brief Called when a new result set and row index are associated with the target 
+ */
 - (void) PGTSSetRow: (int) row resultSet: (PGTSResultSet *) res;
 @end

Sources/PGTSResultSet.mm

 
 /** 
  * \internal
- * Result set for a query.
+ * \brief Result set for a query.
+ *
  * A result set contains rows that may be iterated by the user.
  */
 @implementation PGTSConcreteResultSet
 }
 
 /**
- * Current row with field names as keys.
+ * \brief Current row with field names as keys.
+ *
  * NSNull is used in place of nil.
  */
 - (NSDictionary *) currentRowAsDictionary
     return retval;
 }
 
-/** Move to the beginning of the result set */
+/** \brief Move to the beginning of the result set */
 - (void) goBeforeFirstRow
 {
     [self goToRow: -1];
 @implementation PGTSConcreteResultSet (FieldAccessors)
 
 /**
- * Set the class that should be used with a specific field.
+ * \brief Set the class that should be used with a specific field.
  * @{
  */
 - (BOOL) setClass: (Class) aClass forKey: (NSString *) aName

Sources/PGTSRoleDescription.m

 }
 
 /** 
- * Check if given role is member of self.
+ * \brief Check if given role is member of self.
  * \param aRole The role to be tested. May be a proxy.
  */
 - (BOOL) hasMember: (PGTSRoleDescription *) aRole

Sources/PGTSTableDescription.m

 
 /** 
  * \internal
- * Database table
+ * \brief Database table
  */
 @implementation PGTSTableDescription
 

Sources/PGTSTypeDescription.m

 
 /** 
  * \internal
- * Data type in a database.
+ * \brief Data type in a database.
  */
 @implementation PGTSTypeDescription