Updating comments

parsers/caves.py

@@ -88,7 +88,7 @@ def do_pending_cave(k, url, area):
     '''
     def get_survex_file(k):
         '''Guesses at and finds a survex file for this pending cave.
-        Convoluted. Sorry. Needs rewriting
+        Convoluted. Needs rewriting
         '''
         if k[0:3] == "162":
             id = Path(k[5:])
@@ -199,6 +199,9 @@ def do_pending_cave(k, url, area):
 
 
 def readentrance(filename):
+    '''Reads an enrance description from the .html file
+    Convoluted. Sorry.This is as I inherited it and I haven't fiddled with it. Needs rewriting
+    '''
     global entrances_xslug
     global caves_xslug
     global areas_xslug
@@ -296,7 +299,9 @@ def readentrance(filename):
             # print(message)
 
 def readcave(filename):
-    '''Assumes any area it hasn't seen before is a subarea of 1623
+    '''Reads an enrance description from the .html file
+    Convoluted. Sorry.This is as I inherited it and I haven't fiddled with it. Needs rewriting
+    Assumes any area it hasn't seen before is a subarea of 1623
     '''
     global entrances_xslug
     global caves_xslug
@@ -447,6 +452,8 @@ def readcave(filename):
             print(message)
 
 def getXML(text, itemname, minItems = 1, maxItems = None, printwarnings = True, context = ""):
+    """Reads a single XML tag
+    """
     items = re.findall("<%(itemname)s>(.*?)</%(itemname)s>" % {"itemname": itemname}, text, re.S)
     if len(items) < minItems and printwarnings:
         message = " ! %(count)i x %(itemname)s found, at least %(min)i expected. Load ABORT. " % {"count": len(items),

parsers/survex.py

@@ -25,7 +25,8 @@ It also scans the Loser repo for all the svx files, which it loads individually
 
 todo = '''
         
--#BUG, if *date comes after *team, the person's date is not set at all. It needs re-setting at the endof the block.
+-#BUG, if *date comes after *team, the person's date is not set at all. 
+It needs re-setting at the end of the block.
 
 - LoadSurvexFile() Creates a new current survexfile and valid .survexdirectory
         The survexblock passed-in is not necessarily the parent. FIX THIS.
@@ -49,6 +50,8 @@ debugprinttrigger = "!"
 # debugprinttrigger = "caves-1623/40/old/EisSVH"
 
 class MapLocations(object):
+    """Class used only for identifying teh entrance locations
+    """
     p = [
         ("laser.0_7", "BNase", "Reference", "Bräuning Nase laser point"),
         ("226-96", "BZkn", "Reference", "Bräuning Zinken trig point"),
@@ -89,6 +92,9 @@ class MapLocations(object):
         return "{} map locations".format(len(self.p))
         
 def get_offending_filename(path):
+    """Used to provide the URL for a line in the DataErrors page
+    whcih reports problems on importing data into troggle
+    """
     return "/survexfile/" + path + ".svx"
 
 class SurvexLeg():
@@ -222,13 +228,9 @@ class LoadingSurvex():
         *team "Anthony Day" notes pictures tape    - this is how the survex documentation says it should be done
         We have a huge variety of abbreviations and mispellings. The most laconic being 
         *team gb, bl
-        If you look at e.g. http://expo.survex.com/survexfile/161#T_caves-1623/161/lhr/alllhr
-        you will see than have the team members are recognised by this parser, but not recognised by the
-        wider troggle system (the name is not a hyperlink) - apparently randomly. 
-        GetPersonExpeditionNameLookup() needs to be fixed.
         
-        personrole is used to record that a person was on a trip, NOT the role they played.
+        personrole is used to record that a person was on a survex trip, NOT the role they played.
-        (NB PersonTrip is a logbook thing)
+        (NB PersonTrip is a logbook thing, not a survex thing. Yes they could be merged, maybe.)
         """
         def record_team_member(tm, survexblock):
             tm = tm.strip('\"\'').strip()
@@ -321,7 +323,7 @@ class LoadingSurvex():
 
     def LoadSurvexUnits(self, survexblock, line):
         # all for 4 survex files with measurements in feet. bugger.
-        # Won't need this once we move to using cavern output for lengths
+        # Won't need this once we move to using cavern or d3dump output for lengths
         tapeunits = self.rx_tapelng.match(line) # tape|length
         if not tapeunits:
             return
@@ -440,7 +442,8 @@ class LoadingSurvex():
         the rest is discarded after error-checking.
         Now skipping the error checking - returns as soon as the leg is not one we count.
         
-        REPLACE ALL THIS by reading the .log output of cavern for the file. But we need the lengths per Block, not by File.  Hmm.
+        REPLACE ALL THIS by reading the .log output of cavern for the file. 
+        But we need the lengths per Block, not by File.  dump3d will do lengths per block.
         """
         invalid_clino = 180.0
         invalid_compass = 720.0
@@ -591,6 +594,8 @@ class LoadingSurvex():
         
        
     def LoadSurvexRef(self, survexblock, args):
+        """Interpret the *ref record, and all the many variants
+        """
         #print(self.insp+ "*REF ---- '"+ args +"'")
         url= get_offending_filename(survexblock.survexfile.path)
         # *REF but also ; Ref      years from 1960 to 2039
@@ -660,6 +665,8 @@ class LoadingSurvex():
             DataIssue.objects.create(parser='survex', message=message, url=url)
 
     def TickSurvexQM(self, survexblock, qmtick):
+        """Interpret the specially formatted comment which is a QM TICKED statement
+        """
         # Now we need to find the correct QM object. It will be in the same block and have the same number.
        
         try:
@@ -677,6 +684,8 @@ class LoadingSurvex():
         qm[0].save()
 
     def LoadSurvexQM(self, survexblock, qmline):
+        """Interpret the specially formatted comment which is a QM definition
+        """
         insp = self.insp
 
         qm_no = qmline.group(1) # this may not be unique across multiple survex files
@@ -1168,6 +1177,8 @@ class LoadingSurvex():
                     print(" # POP  'any' flag now:'{}'  was:{} ".format(self.flagsstar["skiplegs"], oldflags["skiplegs"]))
 
         def starstatement(star):
+            """Interprets a survex comamnd where * is the first character on the line, e.g. *begin
+            """
             nonlocal survexblock
             nonlocal blkid
             nonlocal pathlist