From 8ad2e8798589d819867879f9d0b3fc8994a10bf2 Mon Sep 17 00:00:00 2001
From: Lars Kiesow <lkiesow@uos.de>
Date: Sun, 28 Apr 2013 21:59:56 +0200
Subject: [PATCH] feedgenerator: finished module docs

---
 feedgenerator/entry.py | 40 ++++------------------------------------
 feedgenerator/util.py  | 10 ++++++++++
 2 files changed, 14 insertions(+), 36 deletions(-)

diff --git a/feedgenerator/entry.py b/feedgenerator/entry.py
index 177c88d..f2a122e 100644
--- a/feedgenerator/entry.py
+++ b/feedgenerator/entry.py
@@ -549,6 +549,7 @@ class FeedEntry:
 		:param url: URL of the media object.
 		:param length: Size of the media in bytes.
 		:param type: Mimetype of the linked media.
+		:returns: Data of the enclosure element.
 		'''
 		if not uri is None:
 			self.link( href=url, rel='enclosure', type=type, length=length )
@@ -559,43 +560,10 @@ class FeedEntry:
 		'''Get or set the ttl value. It is an RSS only element. ttl stands for
 		time to live. It's a number of minutes that indicates how long a channel
 		can be cached before refreshing from the source.
+
+		:param ttl: Integer value representing the time to live.
+		:returns: Time to live of of the entry.
 		'''
 		if not ttl is None:
 			self.__rss_ttl = int(ttl)
 		return self.__rss_ttl
-
-
-
-if __name__ == '__main__':
-	fg = FeedGenerator()
-	fg.id('http://lernfunk.de/_MEDIAID_123')
-	fg.title('Testfeed')
-	fg.author( {'name':'Lars Kiesow','email':'lkiesow@uos.de'} )
-	fg.link( href='http://example.com', rel='alternate' )
-	fg.category(term='test')
-	fg.contributor( name='Lars Kiesow', email='lkiesow@uos.de' )
-	fg.contributor( name='John Doe', email='jdoe@example.com' )
-	fg.icon('http://ex.com/icon.jpg')
-	fg.logo('http://ex.com/logo.jpg')
-	fg.rights('cc-by')
-	fg.subtitle('This is a cool feed!')
-	fg.link( href='http://larskiesow.de/test.atom', rel='self' )
-	fg.language('de')
-	fe = fg.add_entry()
-	fe.id('http://lernfunk.de/_MEDIAID_123#1')
-	fe.title('First Element')
-	fe.content('''Lorem ipsum dolor sit amet, consectetur adipiscing elit. Tamen
-			aberramus a proposito, et, ne longius, prorsus, inquam, Piso, si ista
-			mala sunt, placet. Aut etiam, ut vestitum, sic sententiam habeas aliam
-			domesticam, aliam forensem, ut in fronte ostentatio sit, intus veritas
-			occultetur? Cum id fugiunt, re eadem defendunt, quae Peripatetici,
-			verba.''')
-	fe.summary('Lorem ipsum dolor sit amet, consectetur adipiscing elit...')
-	fe.link( href='http://example.com', rel='alternate' )
-	fe.author( name='Lars Kiesow', email='lkiesow@uos.de' )
-
-	fg.atom_file('test.atom')
-	fg.rss_file('test.rss')
-
-	#print fg.atom_str(pretty=True)
-	print fg.rss_str(pretty=True)
diff --git a/feedgenerator/util.py b/feedgenerator/util.py
index 90c3e8c..c164024 100644
--- a/feedgenerator/util.py
+++ b/feedgenerator/util.py
@@ -14,6 +14,16 @@
 
 
 def ensure_format(val, allowed, required, allowed_values={}):
+	'''Takes a dictionary or a list of dictionaries and check if all keys are in
+	the set of allowed keys, if all required keys are present and if the values
+	of a specific key are ok.
+
+	:param val: Dictionaries to check.
+	:param allowed: Set of allowed keys.
+	:param required: Set of required keys.
+	:param allowed_values: Dictionary with keys and sets of their allowed values.
+	:returns: List of checked dictionaries.
+	'''
 	if not val:
 		return None
 	# Make shure that we have a list of dicts. Even if there is only one.