[Checkins] SVN: Sandbox/nadako/z3c.sharedmimeinfo/trunk/src/z3c/sharedmimeinfo/interfaces.py Clean up interface documentation.

[Dan Korostelev]

Log message for revision 103653:
  Clean up interface documentation.

Changed:
  U   Sandbox/nadako/z3c.sharedmimeinfo/trunk/src/z3c/sharedmimeinfo/interfaces.py

-=-
Modified: Sandbox/nadako/z3c.sharedmimeinfo/trunk/src/z3c/sharedmimeinfo/interfaces.py
===================================================================
--- Sandbox/nadako/z3c.sharedmimeinfo/trunk/src/z3c/sharedmimeinfo/interfaces.py	2009-09-08 17:18:29 UTC (rev 103652)
+++ Sandbox/nadako/z3c.sharedmimeinfo/trunk/src/z3c/sharedmimeinfo/interfaces.py	2009-09-08 17:38:06 UTC (rev 103653)
@@ -16,42 +16,49 @@
 $Id$
 """
 from zope.interface import Interface
-from zope.schema import ASCIILine, TextLine
+from zope.schema import TextLine
 
 
 class IMIMETypesUtility(Interface):
     """MIME type guessing utility"""
     
     def getTypeByFileName(filename):
-        """Return type guessed by filename"""
+        """Guess type by filename.
+        
+        Return an IMIMEType object or None, if no matching mime type found.
+        """
     
     def getTypeByContents(file, min_priority=0, max_priority=100):
-        """Return type guessed by data. Accepts file-like object"""
+        """Guess type by data, using "magic" (byte matching).
         
+        file argument is a file-like object.
+
+        min_priority and max_priority control the range of magic rules to use,
+        rules with lower priority are more generic, while ones with higher
+        priority are more specific. See shared-mime-info specification for
+        more details.
+        
+        Return an IMIMEType object or None, if not matching mime type found.
+        """
+        
     def getType(filename=None, file=None):
         """Guess content type either by file name or contents or both.
         
-        At least one of these arguments should be provided.
+        filename is a string, file is a file-like object. At least one of
+        these arguments should be provided.
         
-        This method always returns some useful mimetype, 
-        ``application/octet-stream`` or ``text/plain``.
+        This method always returns an usable IMIMEType object, using
+        application/octet-stream and text/plain as fallback mime types.
         """
 
 
 class IMIMEType(Interface):
-    """Single MIME type representation"""
+    """MIME type representation
     
-    media = ASCIILine(
-        title=u'Media',
-        required=True,
-        readonly=True)
-
-    subtype = ASCIILine(
-        title=u'Subtype',
-        required=True,
-        readonly=True)
-
-    title = TextLine(
-        title=u'Title',
-        required=True,
-        readonly=True)
+    Objects providing this interface also act as the unicode strings with
+    the <media>/<subtype> value.
+    """
+    
+    media = TextLine(title=u'Media', required=True, readonly=True)
+    subtype = TextLine(title=u'Subtype', required=True, readonly=True)
+    title = TextLine(title=u'Title', required=True, readonly=True)