Module documentation docstrings

urls.py

@@ -10,16 +10,25 @@ from troggle.core.views_other import logbook_entry_suggestions
 from troggle.core.views_caves import ent, prospecting_image
 from troggle.core.views_statistics import pathsreport, stats
 from flatpages import views as flatviews
+"""This sets the actualurlpatterns[] and urlpatterns[] lists which django uses
+to resolve urls - in both directions as these are declarative. It runs
+django autodiscover() first:
+https://docs.djangoproject.com/en/1.11/ref/contrib/admin/#discovery-of-admin-files
+which may no longer be necessary in Django 1.11.29
 
+HOW THIS WORKS
+This is a "url dispatcher" - something needed by every web framework.
+url( <regular expression that matches the thing in the web browser>,
+<reference to python function in 'core' folder>, <optional name>)
+
+Django also provides the reverse function: given an an object, provide the URL
+which is vital to writing code for the webapp. So the URL dispatch is declarative.
+"""
 admin.autodiscover()
 
-#    HOW DOES THIS WORK:
-#    This is a "url dispatcher" - something needed by every web framework.
-#    url( <regular expression that matches the thing in the web browser>,
-#         <reference to python function in 'core' folder>, <optional name>)
-
-#    Django also provides the reverse function: given an an object, provide the URL
-#    which is vital to writing code for the webapp. So the URL dispatch is declarative.
+# Many of these patterns do not work because troggle spent many years broken and we have
+# not yet restored all the functions. Some may have never been fully implemented in
+# the first place and what they were intended to provide is obscure.
 
 actualurlpatterns = [
     url(r'^troggle$',    views_other.frontpage,      name="frontpage"),