Adding comments.

apps/news/views.py

@@ -1,6 +1,10 @@
-#
-# News display.
-#
+"""
+This is a very simple news application, with most of the expected features
+like:
+
+   * News categories/topics
+   * Searchable archives
+"""
 from django.shortcuts import render_to_response, get_object_or_404
 from django.template import RequestContext
 import django.views.generic.list_detail as gv_list_detail
@@ -23,13 +27,17 @@ sidebar = """
 
 class SearchForm(forms.Form):
    """
-   Class to represent a news search form under Django's newforms.
+   Class to represent a news search form under Django's newforms. This is used
+   to validate the input on the search_form view, as well as the search_results
+   view when we're picking the query out of GET. This makes searching safe
+   via the search form or by directly inputing values via GET key pairs.
    """
    search_terms = forms.CharField(max_length=100, min_length=3, required=True)
 
 def show_news(request, entry_id):
    """
-   Show an individual news entry.
+   Show an individual news entry. Display some basic information along with
+   the title and content.
    """
    news_entry = get_object_or_404(NewsEntry, id=entry_id)
 
@@ -45,6 +53,8 @@ def show_news(request, entry_id):
 def news_archive(request):
    """
    Shows an archive of news entries.
+
+   TODO: Expand this a bit to allow filtering by month/year.
    """
    news_entries = NewsEntry.objects.all().order_by('-date_posted')
    # TODO: Move this to either settings.py or the SQL configuration.
@@ -60,17 +70,20 @@ def news_archive(request):
 
 def search_form(request):
    """
-   Render the news search form.
+   Render the news search form. Don't handle much validation at all. If the
+   user enters a search term that meets the minimum, send them on their way
+   to the results page.
    """
-   debug =""
-
    if request.method == 'GET':
-      debug = "GET"
+      # A GET request was sent to the search page, load the value and
+      # validate it.
       search_form = SearchForm(request.GET)
       if search_form.is_valid():
+         # If the input is good, send them to the results page with the
+         # query attached in GET variables.
          return HttpResponseRedirect('/news/search/results/?search_terms='+ search_form.cleaned_data['search_terms'])
    else:
-      debug = "NOTHING"
+      # Brand new search, nothing has been sent just yet.
       search_form = SearchForm()
 
    pagevars = {
@@ -85,15 +98,22 @@ def search_form(request):
 
 def search_results(request):
    """
-   Shows an archive of news entries.
+   Shows an archive of news entries. Use the generic news browsing template.
    """
    # TODO: Move this to either settings.py or the SQL configuration.
    entries_per_page = 15
 
+   # Load the form values from GET to validate against.
    search_form = SearchForm(request.GET)
+   # You have to call is_valid() or cleaned_data won't be populated.
    valid_search = search_form.is_valid()
+   # This is the safe data that we can pass to queries without huge worry of
+   # badStuff(tm).
    cleaned_get = search_form.cleaned_data
 
+   # Perform searches that match the title and contents.
+   # TODO: Allow the user to specify what to match against and in what
+   # topics/categories.
    news_entries = NewsEntry.objects.filter(Q(title__contains=cleaned_get['search_terms']) | Q(body__contains=cleaned_get['search_terms']))
 
    pagevars = {