 import Foundation
 import CoreData
 
+/// A `NSManagedObjectContext` subclass with the expected default behaviors for use with **AlecrimCoreData** (**ACD**).
+///
+/// - important: This class can be subclassed or used as is. The preferred way to add `Table` properties to a `DataContext`,
+///              however, is writing an extension for it or using the generated extensions by **ACDGen** utility app
+///              when a data context class name is specified at the moment of source code files creation.
+///
+/// - note: Virtually all other **ACD** types (like `Table` or `Attribute`, for example) can be used with "vanilla"
+///         `NSManagedObjectContext` instances too. If so, the framework user will have to write all the custom handling
+///         for the managed object contexts (i.e., *stack*), losing the conveniences provided by this class but achieving
+///         greater control and flexibility about the behaviors she/he wants while also keeping the functionality from other
+///         **ACD** types.
+///
+/// - warning: Mixing `DataContext` and "vanilla" `NSManagedObjextContext` instances is possible but is strongly
+///            discouraged. Most often it is preferable to proceed with one approach (using only `DataContext` instances)
+///            or another (using only `NSManagedObjectContext` instances).
+///
+/// - seealso: `DataContextOptions`, `Table`, `FetchedResultsController`
 public class DataContext: NSManagedObjectContext {
     
     // MARK: - private properties

    
}

private class RootSavingDataContext: DataContext {
    
    private static let savedChildContextUserInfoKey = "com.alecrim.AlecrimCoreData.DataContext.SavedChildContext"

    
    // background context
    
    /// Initializes a background context that has as parent the given context or the root context of the given context.
    ///
    /// - parameter parentContext: The parent or relative context.
    ///
    /// - returns: An initialized background context.
    public convenience init(parentContext: NSManagedObjectContext) {
        self.init(concurrencyType: .PrivateQueueConcurrencyType)
        
