Documentated code except views.py

project/alloc.py

+## File containing allocator function
 from allocation.models import *
 
+## Allocator Function
+# @brief Function to allocate choices to applicants based on their preferences
+# @param univ Name of the institute
+# @return list of applicants which also store their newly allocated choices
 def allocator(univ):
 	insti=Institute.objects.filter(name=univ)[0]
-	
-	insti.is_allocated=True
-	insti.save()
-	a=Applicant.objects.filter(institute__name=univ).order_by('rank')
-	# c=Choice.objects.filter(institute__name=univ)
-	# my_dict=dict([(x,0) for x in c])
-	for x in a:
-		choices=x.ordered_choices()
-		i=0
+	insti.is_allocated=True #< Sets that the institute has allocated atleast once
+	insti.save() #< save changes to institute model instance
+	a=Applicant.objects.filter(institute__name=univ).order_by('rank') #< variable \c a \ stores the list of applicants in order of their ranks
+	for x in a: #< loop over all applicants
+		choices=x.ordered_choices() #< variable \c choices \ stores choices in order of priority of the applicant
+		i=0 
 		flag=True
-		while x.is_float and flag and i<len(choices):
+		while x.is_float and flag and i<len(choices): #< loop over all preferences till allocated
 			if choices[i].capacity>choices[i].seats_filled :
-				given_choice=x.alloted_choice.all()
+				given_choice=x.alloted_choice.all() #< \c given_choice\ stores already alloted choice
 				if given_choice:
 					g=given_choice[0]
 					g.seats_filled=g.seats_filled-1
 					x.alloted_choice.clear()
 					x.save()
 					g.save()
-				clalloc=Allocationcl(choice=choices[i],applicant=x)
+				clalloc=Allocationcl(choice=choices[i],applicant=x) #< link Choice to Applicant using Application model
 				clalloc.save()
 				choices[i].seats_filled=choices[i].seats_filled+1
 				choices[i].save()
 				flag=False
-				# x.alloted_choice.clear()
-				# x.alloted_choice.create(choices[i])
-		# if(temp!=1)
-			# x.alloted_choice.clear()
-			# x.alloted_choice.create(Null_choice)
-		# 	cll=Allocationcl(choice=Null_choice,applicant=x)
 			i=i+1
 	return a
\ No newline at end of file

project/allocation/admin.py

+## Admin Site View
+# Used to modify the admin site
 from django.contrib import admin
-
 from .models import *
 
-# class UnivAppInLine(admin.TabularInline):
-# 	model=UnivApp
-# 	extra=0
-
-# class UnivChoiceInLine(admin.TabularInline):
-# 	model=UnivChoice
-# 	extra=0
-
 class ChoiceInline(admin.TabularInline):
-	model = Application  #https://stackoverflow.com/questions/5947843/django-how-does-manytomanyfield-with-through-appear-in-admin
+	model = Application  
 	extra = 2 
 
 class AllotedChoiceToAppInLine(admin.TabularInline):
@@ -30,7 +23,6 @@ class InstituteAdmin(admin.ModelAdmin):
 class ChoiceAdmin(admin.ModelAdmin):
 	fields=['choice_name', 'capacity','institute', 'seats_filled']
 	list_display=['choice_name','institute', 'capacity', 'seats_filled' ]
-	# inlines=[UnivChoiceInLine]
 
 admin.site.register(Institute, InstituteAdmin)
 admin.site.register(Choice, ChoiceAdmin)

project/allocation/apps.py

 from django.apps import AppConfig
 
-
 class AllocationConfig(AppConfig):
-    name = 'allocation'
+    name = 'allocation'
\ No newline at end of file

project/allocation/forms.py

+## Form Used for Registration
 from django import forms
 from allocation.models import *
 from django.forms import ModelForm
-# from registration.forms import RegistrationForm
-# import re
 from django.contrib.auth.models import User
-# from django.core.exceptions import ObjectDoesNotExist
 from django import forms
 from django.contrib.auth.forms import UserCreationForm
 
+## Registration Form
+# Registration form used to register new institutes to allow using our services
 class InstiForm(UserCreationForm):
-    # name = forms.DateField(help_text='Required. Format: YYYY-MM-DD')
+    ## Metadata
     class Meta:
-        model = User
-        fields = ['username', 'password1', 'password2', ]
-
+        model = User #< Form to create new user model
+        fields = ['username', 'password1', 'password2', ] #< Fields to be taken input
\ No newline at end of file
-	# username = forms.CharField(label='Username', max_length=30)
-	# email = forms.EmailField(label='Email')
-	# class Meta:
-	# 	model = Institute
-	# 	fields=['name',]
-	# 	# widgets=
-	# password1 = forms.CharField(label='Password', widget=forms.PasswordInput())
-	# password2 = forms.CharField(label='Password (Again)', widget=forms.PasswordInput())
-	# def clean_password2(self):
-	# 	if 'password1' in self.cleaned_data:
-	# 		password1 = self.cleaned_data['password1']
-	# 		password2 = self.cleaned_data['password2']
-	# 		if password1 == password2:
-	# 			return password2
-	# 	raise forms.ValidationError('Passwords do not match.')
-	# def clean_username(self):
-	# 	username = self.cleaned_data['name']
-	# 	if not re.search(r'^\w+$', username):
-	# 		raise forms.ValidationError('Username can only contain alphanumeric characters and the underscore.')
-	# 	try:
-	# 		User.objects.get(username=username)
-	# 	except ObjectDoesNotExist:
-	# 		return username
-	# 	raise forms.ValidationError('Username is already taken.')
-
-# class PreferenceForm(forms.Form):
-#     name = forms.CharField()
-#     rank = forms.IntegerField()
-#     choices = forms.ModelMultipleChoiceField(queryset=Choice.objects.all())
-
-# class PreferenceForm(ModelForm):
-# 	class Meta:
-# 		model = Applicant
-# 		fields = ['name', 'rank', 'choices']
-
-# class AppForm(ModelForm):
-#      def __init__(self, *args, **kwargs):
-#          super(AppForm, self).__init__(*args, **kwargs)
-#          applicant=Applicant.objects.filter(name=self.request.user.username)
-#          self.fields['choices'].queryset = Choice.objects.filter(institute=applicant__institute)
-#     class Meta:
-#         model = Application
-#         fields = ['applicant','choice', 'priority']
\ No newline at end of file

project/allocation/models.py

+## Models file
+# It contains all the models used to define the database
 from __future__ import unicode_literals
 from django.db import models
 from django.core.validators import MaxValueValidator, MinValueValidator
-# import CsvModel
 import csv
 import os
 
-
+## Models file
+# It contains all the models used to define the database
+## Institute Model
+# @brief Stores information about all institutes in a table
 class Institute(models.Model):
-	name=models.CharField(max_length=200)
-	is_allocated=models.BooleanField(default=False)
-	# username=models.CharField(max_length=200)
-	# email=models.EmailField(max_length=200)
+	name=models.CharField(max_length=200) #< name of the Institute
+	is_allocated=models.BooleanField(default=False) #< Stores if atleast \f$1^{st}\f$ round is over or not
+	## String Conversion
+	# @param self Pointer to itself
+	# @return name Name of institute
 	def __str__(self):
 		return self.name
+	## Metadata
 	class Meta:
-		verbose_name='Institute'
-		verbose_name_plural='Institutes'
-# @receiver(post_save, sender=User)
-# def update_user_profile(sender, instance, created, **kwargs):
-# 	if created:
-# 		Profile.objects.create(user=instance)
-# 	instance.profile.save()
+		verbose_name='Institute' #< Display name
+		verbose_name_plural='Institutes' #< Plural display name
 
+## Choice Model
+# @brief Stores various choices in a table
 class Choice(models.Model):
-	choice_name = models.CharField(max_length=200)
-	institute=models.ForeignKey(Institute, on_delete=models.CASCADE, related_name='choices')
-	capacity = models.IntegerField()
-	seats_filled=models.IntegerField(default=0)
+	choice_name = models.CharField(max_length=200) #< object containing name of choice
+	institute=models.ForeignKey(Institute, on_delete=models.CASCADE, related_name='choices') #< Object containing related institute primary key
+	capacity = models.IntegerField() #< Object containing maximum number of applicants allowed
+	seats_filled=models.IntegerField(default=0) #< Object containing number of seats currently occupied
+	## String Conversion
+	# @param self Pointer to itself
+	# @return name Name of Choice
 	def __str__(self):
 		return self.choice_name
 
-# Null_Choice=Choice.objects.create(choice_name="None",capacity=1000)
-# Null_Choice.save()
-
+## Applicant Model
+# @brief Stores various applicants in a table
 class Applicant(models.Model):
-	institute=models.ForeignKey(Institute,on_delete=models.CASCADE,related_name='applicants')
-	choices = models.ManyToManyField(Choice, through='Application', related_name='applicants')
-	name = models.CharField(max_length=200)
-	alloted_choice = models.ManyToManyField(Choice, through='Allocationcl', related_name='alloted_applicant')
-	rank = models.IntegerField(validators=[MinValueValidator(1)])
-	is_float=models.BooleanField(default=True)
+	institute=models.ForeignKey(Institute,on_delete=models.CASCADE,related_name='applicants') #< Object containing foreign key to relate Applicant and Institute
+	choices = models.ManyToManyField(Choice, through='Application', related_name='applicants') #< Foreign Keys relating Applicant to all the preferred choices
+	name = models.CharField(max_length=200) #< Object containing name of Applicant
+	alloted_choice = models.ManyToManyField(Choice, through='Allocationcl', related_name='alloted_applicant') # Foreign Key to relate Applicant to allocated choice
+	rank = models.IntegerField(validators=[MinValueValidator(1)]) #< Integer object storing rank of Applicant
+	is_float=models.BooleanField(default=True) #< Boolean Field to store current status opted by  the student to determine fereze, float and drop
+	## String Conversion
+	# @param self Pointer to itself
+	# @return name Name of Applicant
 	def __str__(self):
 		return self.name
+	## Ordered Choices
+	# @brief Function to give all the choices as per preference of the Applicant
+	# @param self Pointer to itself
+	# @return list of choices in order of preference
 	def ordered_choices(self):  
-	#https://stackoverflow.com/questions/934779/django-order-a-model-by-a-many-to-many-field
-		"Return a properly ordered set of choices"
 		return self.choices.all().order_by('application__priority')
 
+## Application Model
+# @brief Links an Applicant to a Choice through a model
 class Application(models.Model):
-	applicant = models.ForeignKey(Applicant, on_delete=models.CASCADE)
-	choice = models.ForeignKey(Choice, on_delete=models.CASCADE)
-	priority = models.IntegerField(validators=[MinValueValidator(1)])
+	applicant = models.ForeignKey(Applicant, on_delete=models.CASCADE) #< Applicant to be linked
+	choice = models.ForeignKey(Choice, on_delete=models.CASCADE) #< Choice chosen to be linked
+	priority = models.IntegerField(validators=[MinValueValidator(1)]) #< Preference given to the choice by the Applicant
+	## Metadata
 	class Meta:
-		# if you have an inline configured in the admin, this will 
-		# make the roles order properly 
-
 		ordering = ['priority'] 
 
-
+## Application Model
+# @brief Links allocated Choices to their Applicants through a model
 class Allocationcl(models.Model):
-	choice = models.ForeignKey(Choice, on_delete=models.CASCADE)
-	applicant = models.ForeignKey(Applicant, on_delete=models.CASCADE)
-	# priority = models.IntegerField()
+	choice = models.ForeignKey(Choice, on_delete=models.CASCADE) #< Foreign key to link the allocated choice
+	applicant = models.ForeignKey(Applicant, on_delete=models.CASCADE) #< Foreign key to link the Applicants
+	## Metadata
 	class Meta:
-		# if you have an inline configured in the admin, this will 
-		# make the roles order properly 
-		verbose_name='Allocated Choice'
-		verbose_name_plural='Allocated Choice'
+		verbose_name='Allocated Choice' #< Display Name
+		verbose_name_plural='Allocated Choice' #< Plural display name
+		ordering = ['applicant__rank'] #< used to return applicants in order of their ranks
\ No newline at end of file
-		ordering = ['applicant__rank']
-
-# class UnivChoice(models.Model):
-# ,limit_choices_to={'institute':applicant.institute}
-# 	choice=models.ForeignKey(Choice,on_delete=models.CASCADE)
-# 	university=models.ForeignKey(University,on_delete=models.CASCADE)
-# , limit_choices_to={'university__name':'applicant_university__name'}
-# class UnivApp(models.Model):
-# 	applicant=models.ForeignKey(Applicant,on_delete=models.CASCADE)
-# 	university=models.ForeignKey(University,on_delete=models.CASCADE)
-# 	class Meta:
-# 		ordering=['applicant__rank']
\ No newline at end of file

project/allocation/urls.py

+## URL File
+# Contains Information about active urls of allocation app
 from django.conf.urls import url, include
 from . import views
 from django.contrib.auth import urls
 from django.contrib.auth import views as auth_views
 
 app_name = 'allocation'
-urlpatterns = [
-    url(r'^$', views.index, name='index'),
-    #url(r'^submit$', views.submit, name='submit'),
-    url(r'^admin$', views.admin1, name='admin1'),
-    url(r'^admin/choices$', views.ChoiceListView.as_view(), name='choice_list'),
-    url(r'^admin/applicants$', views.ApplicantListView.as_view(), name='applicant_list'),
-    url(r'^choice/(?P<pk>\d+)$', views.ChoiceDetailView.as_view(), name='choice-detail'),
-    url(r'^applicant/(?P<pk>\d+)$', views.ApplicantDetailView.as_view(), name='applicant-detail'),
-    url(r'^choice/create$', views.ChoiceCreateView.as_view(), name='choice-create'),
-    url(r'^choice/(?P<pk>\d+)/update$', views.ChoiceUpdate.as_view(), name='choice-update'),
-    url(r'^choice/(?P<pk>\d+)/delete$', views.ChoiceDelete.as_view(), name='choice-delete'),
-    url(r'^applicant/(?P<pk>\d+)/update$', views.ApplicantUpdate.as_view(), name='applicant-update'),
-    url(r'^applicant/(?P<pk>\d+)/delete$', views.ApplicantDelete.as_view(), name='applicant-delete'),
-    url(r'^choice_make$', views.choice_make, name='choice_make'),
-    url(r'^applicant_make$', views.applicant_make, name='applicant_make'),
-    url(r'^button_action$', views.button_action, name='button_action'),
-    url(r'^register/$', views.signup),
-    url(r'^freeze$', views.freeze, name='freeze'),
-    url(r'^float$', views.float, name='float'),
-    url(r'^drop$', views.drop, name='drop'),
-    #url(r'^admin/choices$', views.ChoiceListView.as_view(), name='choice_list'),
-    #url(r'^admin/applicants$', views.ApplicantListView.as_view(), name='applicant_list'),
 
-    #url(r'^login/$', auth_views.login,name='login'),
-    #url(r'^logout/$', auth_views.logout, name='logout1'),
+## URL Patterns
+# @brief Matches the URL and redirects accordingly
+urlpatterns = [
+    url(r'^$', views.index, name='index'), #< creates URL for student login
+    url(r'^admin$', views.admin1, name='admin1'), #< creates URL for Institute login
+    url(r'^admin/choices$', views.ChoiceListView.as_view(), name='choice_list'), #< creates URL to display all choices in Institute Login
+    url(r'^admin/applicants$', views.ApplicantListView.as_view(), name='applicant_list'), #< creates URL to display all applicants in Institute Login
+    url(r'^choice/(?P<pk>\d+)$', views.ChoiceDetailView.as_view(), name='choice-detail'), #< creates URL to display a particular choice in Institute Login
+    url(r'^applicant/(?P<pk>\d+)$', views.ApplicantDetailView.as_view(), name='applicant-detail'), #< creates URL to display a particular applicant in Institute Login
+    url(r'^choice/create$', views.ChoiceCreateView.as_view(), name='choice-create'), #< creates URL to create a particular choice in Institute Login
+    url(r'^choice/(?P<pk>\d+)/update$', views.ChoiceUpdate.as_view(), name='choice-update'), #< creates URL to update a particular choice in Institute Login
+    url(r'^choice/(?P<pk>\d+)/delete$', views.ChoiceDelete.as_view(), name='choice-delete'), #< creates URL to deleten a particular choice in Institute Login
+    url(r'^applicant/(?P<pk>\d+)/update$', views.ApplicantUpdate.as_view(), name='applicant-update'), #< creates URL to update a particular applicant in Institute Login
+    url(r'^applicant/(?P<pk>\d+)/delete$', views.ApplicantDelete.as_view(), name='applicant-delete'), #< creates URL to delete a particular applicant in Institute Login
+    url(r'^choice_make$', views.choice_make, name='choice_make'), #< creates URL to create choices through csv file in Institute Login
+    url(r'^applicant_make$', views.applicant_make, name='applicant_make'), #< creates URL to create applicants through csv file in Institute Login
+    url(r'^button_action$', views.button_action, name='button_action'), #< Used to call the allocator function in Institute login
+    url(r'^register/$', views.signup), #< creates URL for registration of new Institutes
+    url(r'^freeze$', views.freeze, name='freeze'), #< URL for Freeze button in Applicant login
+    url(r'^float$', views.float, name='float'), #< URL for Float button in Applicant login
+    url(r'^drop$', views.drop, name='drop'), #< URL for Drop button in Applicant login
 ]
\ No newline at end of file

project/allocation/views.py

@@ -3,7 +3,6 @@ from django.contrib.auth import authenticate
 from django.contrib.auth.decorators import login_required
 from django.contrib.auth.models import User
 from allocation.models import * 
-#from allocation.forms import AppForm
 from django.forms import modelformset_factory, formset_factory, modelform_factory, ModelForm
 from django.views import generic
 from django.views.generic.edit import *
@@ -17,25 +16,6 @@ from django.urls import reverse_lazy
 from allocation.forms import *
 from alloc import *
 
-# @login_required(login_url='/admin/login')
-# def index(request): #for /allocation
-#   applicant=Applicant.objects.filter(name=request.user.username)[0]
-#   # form = PreferenceForm(
-#   #   initial={'name': applicant.name , 'rank': applicant.rank}
-#   #   )
-#   form = ArticleForm(instance=applicant)
-#   return render(request, 'allocation/index.html', {'applicant': applicant, 'form': form})
-
-# def register_page(request):
-# 	if request.method == 'POST':
-# 		form = InstiForm(request.POST)
-# 		if form.is_valid():
-# 			user = User.objects.create_user(username=form.cleaned_data['name'],password=form.cleaned_data['password1'],email=form.cleaned_data['email'])
-# 			return HttpResponseRedirect('/')
-# 	form = InstiForm()
-# 	variables = RequestContext(request, {'form': form})
-# 	return render_to_response('registration/register.html',variables)
-
 def signup(request):
     if request.method == 'POST':
         form = InstiForm(request.POST)
@@ -51,11 +31,6 @@ def signup(request):
     return render(request, 'registration/register.html', {'form': form})
 
 def button_action(request):
-    # value = request.POST["prikey"]
-    # value = int(value.split('/')[-3])
-    # name = Institute.objects.get(pk=value).name
-    # allocator(name)
-    # return HttpResponse("success")
     institute=request.user.username
     allocator(institute)
     return HttpResponse("success")
@@ -74,7 +49,6 @@ def choice_make(request):
         institute = get_object_or_404(Institute, name=user_name)
         for line in lines:
             line =  line.split(',')
-            # tmp = Choice.objects.create(choice_name=line[0],capacity=line[1])
             tmp = institute.choices.create(choice_name=line[0],capacity=line[1])
             tmp.save()
         return HttpResponse("successful")
@@ -90,7 +64,6 @@ def applicant_make(request):
         lines = file_data.split("\n")
         for line in lines:
             line = line.split(',')
-            # tmp = Applicant.objects.create(name = line[0],rank=line[1])
             tmp = institute.applicants.create(name = line[0],rank = line[1])
             tmp.save()
             user = User.objects.create_user(username=line[2],email=line[3],password=line[4])
@@ -99,32 +72,6 @@ def applicant_make(request):
         return HttpResponse("successful")
     return HttpResponse("Error")
 
-
-#AppFormset = modelformset_factory(Application,fields=("choice", "priority" ), extra=5)
-
-# @login_required(login_url='/admin/login')
-# def index(request): #for /allocation
-# 	applicant=get_object_or_404(Applicant, name=request.user.username)
-# 	# form1 = modelform_factory(Applicant, fields=("name", "rank" ))
-# 	formset = AppFormset(queryset=Application.objects.filter(applicant=applicant),)
-# 	return render(request, 'allocation/index.html', {'applicant': applicant,  'formset': formset,})
-
-
-# AppFormset = formset_factory(AppForm, extra=5)
-# @login_required(login_url='/admin/login')
-# def index(request): #for /allocation
-#     applicant=get_object_or_404(Applicant,name=request.user.username)
-#     # form1 = modelform_factory(Applicant, fields=("name", "rank" ))
-#     formset = AppFormset()
-#     return render(request, 'allocation/index.html', {'applicant': applicant,  'formset': formset,})
-
-
-# def submit(request):
-#     if request.method == 'POST':
-#         formset = AppFormset(request.POST)
-#         instances = formset.save()
-#         return HttpResponse("successful")
-
 def make_application_form(applicant1):
     class ApplicationForm(forms.ModelForm):
         choice = forms.ModelChoiceField(queryset=Choice.objects.filter(institute=applicant1.institute))
@@ -139,11 +86,9 @@ def index(request):
     applicant=get_object_or_404(Applicant,name=request.user.username)
     ApplicationForm = make_application_form(applicant)
     ApplicationFormSet = modelformset_factory(Application, form=ApplicationForm, extra=5)
-
     if request.method == "POST":
         formset = ApplicationFormSet(request.POST, queryset=Application.objects.filter(applicant=applicant))
         if formset.is_valid():
-            #Application.objects.filter(applicant=applicant).delete()
             formset.save()
             return render(request, 'allocation/index.html', {'applicant': applicant,  'formset': formset, 'success':True,})
         else:
@@ -158,7 +103,6 @@ def admin1(request):
 	institute=get_object_or_404(Institute,name=request.user.username)
 	return render(request, 'allocation/admin1.html',{'institute': institute})
 
-
 class ChoiceListView(generic.ListView):
 	model = Choice
 	def get_context_data(self, **kwargs):

project/mysite/urls.py

-"""mysite URL Configuration
-
-The `urlpatterns` list routes URLs to views. For more information please see:
-    https://docs.djangoproject.com/en/1.11/topics/http/urls/
-Examples:
-Function views
-    1. Add an import:  from my_app import views
-    2. Add a URL to urlpatterns:  url(r'^$', views.home, name='home')
-Class-based views
-    1. Add an import:  from other_app.views import Home
-    2. Add a URL to urlpatterns:  url(r'^$', Home.as_view(), name='home')
-Including another URLconf
-    1. Import the include() function: from django.conf.urls import url, include
-    2. Add a URL to urlpatterns:  url(r'^blog/', include('blog.urls'))
-"""
+## URL File
+# Contains Information about active urls of the project
 from django.conf.urls import url, include
 from django.contrib import admin
 from django.contrib.auth import views
 from . import views
 from allocation.models import *
 from allocation.forms import *
-# from allocation.views import *
 
+## URL Patterns
+# @brief Matches the URL and redirects accordingly
 urlpatterns = [
-    url(r'^allocation/', include('allocation.urls')),
-    url(r'^admin/', admin.site.urls),
-    url(r'^$',views.index1,name='index1'),
-    # url(r'^register/', allocation.views.signup),
+    url(r'^allocation/', include('allocation.urls')), #< redirects to the allocation app
+    url(r'^admin/', admin.site.urls), #< redirect to admin portal
+    url(r'^$',views.index1,name='index1'), #< redirect to home page view
 ]

project/mysite/views.py

+## Contains the main views of the project
 from django.contrib.auth.decorators import login_required
 from django.contrib.auth.models import User
 from django.shortcuts import render, redirect
 from django.contrib.auth import authenticate, login
 
-
+## Home Page
+# @brief Home Page view of the project
+# @param request
+# @return Http response to show home page
 def index1(request):
     return render(request,'core/home_page.html')
\ No newline at end of file