added more docstrings

polynum_blackboard/forms.py

@@ -17,13 +17,20 @@ import models
 DEFAULT_CATEGORY = ''
 
 def categories():
+    '''Retrieve categories from MyCourse. Beware identifiers are the name of
+       the categories not their id.
+    '''
     yield ('', '---')
     ok, response = django_ws.get_bb_conn().get_categories()
     if ok:
         for category in response.categories:
             yield (category.name, category.name)
 
+
 class func2iter(object):
+    '''Adaptor to transform a generator returning function into an iterator.
+       Each iteration() will come from a new generator.
+    '''
     def __init__(self, func):
         self.func = func
 
@@ -74,6 +81,9 @@ class CreateCourseForm(forms.Form):
                 attrs={'data-entity-type': settings.POLYNUM_BB_UE_DESIGNATION})
 
     def clean(self):
+        '''Check that category, subscription_policy and entity are correctly
+           chosen. Generate a course_id.
+        '''
         cleaned_data = self.cleaned_data
         if not cleaned_data.get('category'):
             cleaned_data['category'] = DEFAULT_CATEGORY

polynum_blackboard/views.py

@@ -19,6 +19,7 @@ from forms import CreateCourseForm
 @require_POST
 @login_required
 def create_course(request):
+    '''Ajax view'''
     form = CreateCourseForm(data=request.POST, request=request)
     ctx = { 'create_course_form': form }
     data = {
@@ -53,11 +54,15 @@ def create_course(request):
 
 @login_required
 def courses_list(request, pk):
+    '''Generate the list of courses with respect to Request object given by
+       pk.
+    '''
     polynum_request = shortcuts.get_object_or_404(Request, pk=pk)
     return shortcuts.render(request, "_select_course.html", { "courses":
         courses_ctx(request, polynum_request)})
 
 def courses_ctx(request, polynum_request):
+    '''Context building for the course selection template.'''
     ctx = {}
     conn = django_ws.get_bb_conn()
     ok, result = conn.get_course_by_owner(request.user.username)