[Docs] Add/update docstrings and license text in every file

calsocial/__init__.py

@@ -14,6 +14,9 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+"""Main module for the Calendar.social app
+"""
+
 from datetime import datetime
 from functools import wraps
 import os
@@ -40,6 +43,9 @@ def get_locale():
 
 
 def template_vars():
+    """Function to inject global template variables
+    """
+
     now = datetime.utcnow()
 
     return {
@@ -50,6 +56,12 @@ def template_vars():
 
 
 def route(*args, **kwargs):
+    """Mark a function as a future route
+
+    Such functions will be iterated over when the application is initialised.  ``*args`` and
+    ``**kwargs`` will be passed verbatim to `Flask.route()`.
+    """
+
     def decorator(func):
         setattr(func, 'routing', (args, kwargs))
 
@@ -59,6 +71,9 @@ def route(*args, **kwargs):
 
 
 class CalendarSocialApp(Flask):
+    """The Calendar.social app
+    """
+
     def __init__(self, name, config=None):
         from .models import db, User, Role
         from .security import security
@@ -93,6 +108,12 @@ class CalendarSocialApp(Flask):
 
     @route('/')
     def hello(self):
+        """View for the main page
+
+        This will display a welcome message for users not logged in; for others, their main
+        calendar view is displayed.
+        """
+
         from .calendar_system.gregorian import GregorianCalendar
 
         if not current_user.is_authenticated:
@@ -109,6 +130,12 @@ class CalendarSocialApp(Flask):
 
     @route('/register', methods=['POST', 'GET'])
     def register(self):
+        """View for user registration
+
+        If the ``REGISTRATION_FAILED`` configuration value is set to ``True`` it displays the
+        registration disabled template.  Otherwise, it performs user registration.
+        """
+
         if not current_app.config['REGISTRATION_ENABLED']:
             return render_template('registration-disabled.html')
 
@@ -132,6 +159,11 @@ class CalendarSocialApp(Flask):
     @route('/new-event', methods=['GET', 'POST'])
     @login_required
     def new_event(self):
+        """View for creating a new event
+
+        This presents a form to the user that allows entering event details.
+        """
+
         from .forms import EventForm
         from .models import db, Event