changeset 1996:8a20af6b9081

add docstrings for Flatland Form subclasses in items module
author Cheer Xiao <xiaqqaix@gmail.com>
date Thu, 14 Feb 2013 21:18:25 +0800
parents 21fb938ab077
children 8c71a45e11f2
files MoinMoin/items/__init__.py MoinMoin/items/content.py
diffstat 2 files changed, 42 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/MoinMoin/items/__init__.py	Wed Feb 13 13:33:57 2013 +0100
+++ b/MoinMoin/items/__init__.py	Thu Feb 14 21:18:25 2013 +0800
@@ -186,8 +186,18 @@
 
 
 class BaseModifyForm(BaseChangeForm):
+    """
+    This class is abstract and only defines two factory methods; see
+    Item._ModifyForm for the implementation.
+    """
     @classmethod
     def from_item(cls, item):
+        """
+        Construct an instance from :item.
+
+        This class method is not supposed to be overriden; subclasses should
+        overrride the _load method instead.
+        """
         form = cls.from_defaults()
         TextCha(form).amend_form()
         form._load(item)
@@ -195,6 +205,13 @@
 
     @classmethod
     def from_request(cls, request):
+        """
+        Construct an instance from :request.
+
+        Since the mapping from HTTP form (unlike from an Item instance) to
+        Flatland Form is straightforward, there should be rarely any need to
+        override this class method.
+        """
         form = cls.from_flat(request.form.items() + request.files.items())
         TextCha(form).amend_form()
         return form
@@ -378,12 +395,23 @@
         return self._save(meta, data, contenttype_guessed=contenttype_guessed, comment=comment)
 
     class _ModifyForm(BaseModifyForm):
-        """Base class for ModifyForm of Item subclasses."""
+        """
+        ModifyForm (the form used on +modify view), sans the content part.
+        Combined dynamically with the ModifyForm of the Content subclass in
+        Contentful.ModifyForm.
+
+        Subclasses of Contentful should generally override this instead of
+        ModifyForm.
+        """
         meta_form = BaseMetaForm
         extra_meta_text = JSON.using(label=L_("Extra MetaData (JSON)")).with_properties(rows=ROWS_META, cols=COLS)
         meta_template = 'modify_meta.html'
 
         def _load(self, item):
+            """
+            Load metadata and data from :item into :self. Used by
+            BaseModifyForm.from_item.
+            """
             meta = item.prepare_meta_for_modify(item.meta)
             # Default value of `policy` argument of Flatland.Dict.set's is
             # 'strict', which causes KeyError to be thrown when meta contains
@@ -396,6 +424,15 @@
             self['content_form']._load(item.content)
 
         def _dump(self, item):
+            """
+            Dump useful data out of :self. :item contains the old item and
+            should not be the primary data source; but it can be useful in case
+            the data in :self is not sufficient.
+
+            :returns: a tuple (meta, data, contenttype_guessed, comment),
+                      suitable as arguments of the same names to pass to
+                      item.modify
+            """
             meta = self['meta_form'].value.copy()
             meta.update(item.meta_text_to_dict(self['extra_meta_text'].value))
             data, contenttype_guessed = self['content_form']._dump(item.content)
--- a/MoinMoin/items/content.py	Wed Feb 13 13:33:57 2013 +0100
+++ b/MoinMoin/items/content.py	Thu Feb 14 21:18:25 2013 +0800
@@ -309,6 +309,10 @@
     data = property(fget=get_data)
 
     class ModifyForm(Form):
+        """
+        The content part of the ModifyForm of an Item subclass. See also the
+        doc of Item._ModifyForm.
+        """
         template = 'modify_binary.html'
         help = """\
 There is no help, you're doomed!