Added a 'getting started' tutorial and a short intro to philo page to the docs. Impro...

[philo.git] / philo / models / base.py

diff --git a/philo/models/base.py b/philo/models/base.py
index c361bdc..9ba1ff6 100644 (file)
--- a/philo/models/base.py
+++ b/philo/models/base.py
@@ -16,6 +16,9 @@ from philo.utils.entities import AttributeMapper, TreeAttributeMapper
 from philo.validators import json_validator
 
 
+__all__ = ('Tag', 'value_content_type_limiter', 'register_value_model', 'unregister_value_model', 'JSONValue', 'ForeignKeyValue', 'ManyToManyValue', 'Attribute', 'Entity', 'TreeEntity')
+
+
 class Tag(models.Model):
        """A simple, generic model for tagging."""
        #: A CharField (max length 255) which contains the name of the tag.
@@ -33,6 +36,7 @@ class Tag(models.Model):
 
 
 class Titled(models.Model):
+       # Use of this model is deprecated.
        title = models.CharField(max_length=255)
        slug = models.SlugField(max_length=255)
        
@@ -43,7 +47,7 @@ class Titled(models.Model):
                abstract = True
 
 
-#: An instance of :class:`ContentTypeRegistryLimiter` which is used to track the content types which can be related to by :class:`ForeignKeyValue`\ s and :class:`ManyToManyValue`\ s.
+#: An instance of :class:`.ContentTypeRegistryLimiter` which is used to track the content types which can be related to by :class:`ForeignKeyValue`\ s and :class:`ManyToManyValue`\ s.
 value_content_type_limiter = ContentTypeRegistryLimiter()
 
 
@@ -96,7 +100,7 @@ class AttributeValue(models.Model):
                abstract = True
 
 
-#: An instance of :class:`ContentTypeSubclassLimiter` which is used to track the content types which are considered valid value models for an :class:`Attribute`.
+#: An instance of :class:`.ContentTypeSubclassLimiter` which is used to track the content types which are considered valid value models for an :class:`Attribute`.
 attribute_value_limiter = ContentTypeSubclassLimiter(AttributeValue)
 
 
@@ -242,7 +246,12 @@ class ManyToManyValue(AttributeValue):
 
 
 class Attribute(models.Model):
-       """Represents an arbitrary key/value pair on an arbitrary :class:`Model` where the key consists of word characters and the value is a subclass of :class:`AttributeValue`."""
+       """
+       :class:`Attribute`\ s exist primarily to let arbitrary data be attached to arbitrary model instances without altering the database schema and without guaranteeing that the data will be available on every instance of that model.
+       
+       Generally, :class:`Attribute`\ s will not be accessed as models; instead, they will be accessed through the :attr:`Entity.attributes` property, which allows direct dictionary getting and setting of the value of an :class:`Attribute` with its key.
+       
+       """
        entity_content_type = models.ForeignKey(ContentType, related_name='attribute_entity_set', verbose_name='Entity type')
        entity_object_id = models.PositiveIntegerField(verbose_name='Entity ID', db_index=True)
        
@@ -310,7 +319,7 @@ class Entity(models.Model):
        
        def get_attribute_mapper(self, mapper=AttributeMapper):
                """
-               Returns a dictionary-like object which can be used to retrieve related :class:`Attribute`\ s' values directly.
+               Returns an :class:`.AttributeMapper` which can be used to retrieve related :class:`Attribute`\ s' values directly.
 
                Example::
 
@@ -492,7 +501,7 @@ class TreeEntity(Entity, TreeModel):
        
        def get_attribute_mapper(self, mapper=None):
                """
-               Returns a dictionary-like object which can be used to retrieve related :class:`Attribute`\ s' values directly. If an attribute with a given key is not related to the :class:`Entity`, then the object will check the parent's attributes.
+               Returns a :class:`.TreeAttributeMapper` or :class:`.AttributeMapper` which can be used to retrieve related :class:`Attribute`\ s' values directly. If an :class:`Attribute` with a given key is not related to the :class:`Entity`, then the mapper will check the parent's attributes.
 
                Example::