Commits

Doug Burke committed 4fa3ebb

Doc updates

Comments (0)

Files changed (61)

Swish/RDF/BuiltInDatatypes.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module collects references and provides access to all of the

Swish/RDF/BuiltInMap.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module collects references and provides access to all of the

Swish/RDF/BuiltInRules.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module collects references and provides access to all of the

Swish/RDF/ClassRestrictionRule.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  MultiParamTypeClasses
 --
 --  This module implements an inference rule based on a restruction on class

Swish/RDF/Datatype.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  ExistentialQuantification, MultiParamTypeClasses
 --
 --  This module defines the structures used by Swish to represent and

Swish/RDF/GraphClass.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  DeriveFunctor, DeriveFoldable, DeriveTraversable, MultiParamTypeClasses
 --
 --  This module defines a Labelled Directed Graph and Label classes,
 --  and the Arc datatype.

Swish/RDF/GraphMatch.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  Uses FlexibleInstances, TypeSynonymInstances, MultiParamTypeClasses pragmas
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  FlexibleInstances, TypeSynonymInstances, MultiParamTypeClasses
 --
 --  This module contains graph-matching logic.
 --
 --  Label index value type
 --------------------------
 --
---  LabelIndex is a unique value assigned to each label, such that
+
+-- | LabelIndex is a unique value assigned to each label, such that
 --  labels with different values are definitely different values
 --  in the graph;  e.g. do not map to each other in the graph
 --  bijection.  The first member is a generation counter that
     => Eq (GenLabelEntry lb lv) where
     (==) = entryEq
 
---  Type for label->index lookup table
+-- | Type for label->index lookup table
 data (Label lb, Eq lv, Show lv) => GenLabelMap lb lv =
     LabelMap Int (LookupMap (GenLabelEntry lb lv))
 
 --  Equivalence class type
 --------------------------
 --
---  Type for equivalence class description
+
+-- | Type for equivalence class description
 --  (An equivalence class is a collection of labels with
 --  the same LabelIndex value.)
 
 --  Augmented graph label value - for graph matching
 ------------------------------------------------------------
 --
---  This instance of class label adds a graph identifier to
+-- | This instance of class label adds a graph identifier to
 --  each variable label, so that variable labels from
 --  different graphs are always seen as distinct values.
 --
             EQ -> compare l1 l2
             GT -> GT
 
---------------
---  graphMatch
---------------
---
---  Graph matching function accepting two lists of arcs and
+-- QUS: why doesn't this return Maybe (LabelMap (ScopedLabel lb)) ?
+
+-- | Graph matching function accepting two lists of arcs and
 --  returning a node map if successful
 --
---  matchable
---          is a function that tests for additional constraints
---          that may prevent the matching of a supplied pair
---          of nodes.  Returns True if the supplied nodes may be
---          matched.  (Used in RDF graph matching for checking
---          that formula assignments are compatible.)
---  gs1     is the first of two graphs to be compared,
---          supplied as a list of arcs.
---  gs2     is the second of two graphs to be compared,
---          supplied as a list of arcs.
---
---  returns a label map that maps each label to an equivalence
---          class identifier, or Nothing if the graphs cannot be
---          matched.
-
 graphMatch :: (Label lb) =>
-    (lb -> lb -> Bool) -> [Arc lb] -> [Arc lb]
+    (lb -> lb -> Bool)
+    -- ^ a function that tests for additional constraints
+    --   that may prevent the matching of a supplied pair
+    --   of nodes.  Returns `True` if the supplied nodes may be
+    --   matched.  (Used in RDF graph matching for checking
+    --   that formula assignments are compatible.)
+    -> [Arc lb] -- ^ the first graph to be compared, as a list of arcs
+    -> [Arc lb] -- ^ the second graph to be compared, as a list of arcs
     -> (Bool,LabelMap (ScopedLabel lb))
+    -- ^ If the first element is `True` then the secondelement maps each label
+    --   to an equivalence class identifier, otherwise it is just
+    --   `emptyMap`.
+    --
 graphMatch matchable gs1 gs2 =
     let
         sgs1    = {- trace "sgs1 " $ -} map (makeScopedArc 1) gs1
     in
         if length ec1 /= length ec2 then (False,emptyMap) else match
 
---  Recursive graph matching function
+-- | Recursive graph matching function
+--
 --  This function assumes that no variable label appears in both graphs.
---  (Function graphMatch, which calls this, ensures that all variable
+--  (Function `graphMatch`, which calls this, ensures that all variable
 --  labels are distinct.)
 --
---  matchable
---          is a function that tests for additional constraints
---          that may prevent the matching of a supplied pair
---          of nodes.  Returns True if the supplied nodes may be
---          matched.
---  guessed is True if a guess has been used before trying this comparison,
---          False if nodes are being matched without any guesswork.
---  gs1     is the first of two lists of arcs (triples) to be compared
---  gs2     is the second of two lists of arcs (triples) to be compared
---  lmap    is the map so far used to map label values to equivalence
---          class values
---  ecpairs list of pairs of corresponding equivalence classes of nodes
---          from gs1 and gs2 that have not been confirmed in 1:1
---          correspondence with each other.
---          Each pair of equivalence classes contains nodes that must
---          be placed in 1:1 correspondence with each other.
+--  TODO:
 --
---  returns a pair (match,map), where 'match' is Tue if the supplied
---          sets of arcs can be matched, in which case 'map' is a
---          corresponding map from labels to equivalence class identifiers.
---          When 'match' is False, 'map' is the most detailed equivalence
---          class map obtained before a mismatch was detected or a guess
---          was required -- this is intended to help identify where the
---          graph mismatch may be.
+--    * replace Equivalence class pair by @(index,[lb],[lb])@ ?
 --
--- [[[TODO:  replace Equivalence class pair by (index,[lb],[lb]) ?]]]
--- [[[TODO:  possible optimization:  the graphMapEq test should be
---           needed only if graphMatch2 has been used to guess a
---           mapping;  either (a) supply flag saying guess has been
---           used, or (b) move test to graphMatch2 and use different
---           test to prevent rechecking for each guess used.]]]
+--    * possible optimization:  the `graphMapEq` test should be
+--      needed only if `graphMatch2` has been used to guess a
+--      mapping;  either: 
+--          a) supply flag saying guess has been used, or
+--          b) move test to `graphMatch2` and use different
+--             test to prevent rechecking for each guess used.
+--
 
-graphMatch1 :: (Label lb) =>  Bool -> (lb -> lb -> Bool)
-    -> [Arc lb] -> [Arc lb]
-    -> LabelMap lb -> [(EquivalenceClass lb,EquivalenceClass lb)]
-    -> (Bool,LabelMap lb)
+graphMatch1 :: 
+  (Label lb) 
+  => Bool
+  -- ^ `True` if a guess has been used before trying this comparison,
+  --   `False` if nodes are being matched without any guesswork
+  -> (lb -> lb -> Bool)
+  -- ^ Test for additional constraints that may prevent the matching
+  --  of a supplied pair of nodes.  Returns `True` if the supplied
+  --  nodes may be matched.
+  -> [Arc lb] 
+  -- ^ (@gs1@ argument)
+  --   first of two lists of arcs (triples) to be compared
+  -> [Arc lb]
+  -- ^ (@gs2@ argument)
+  --   secind of two lists of arcs (triples) to be compared
+  -> LabelMap lb
+  -- ^ the map so far used to map label values to equivalence class
+  --   values
+  -> [(EquivalenceClass lb,EquivalenceClass lb)]
+  -- ^ (the @ecpairs@ argument) list of pairs of corresponding
+  --   equivalence classes of nodes from @gs1@ and @gs2@ that have not
+  --   been confirmed in 1:1 correspondence with each other.  Each
+  --   pair of equivalence classes contains nodes that must be placed
+  --   in 1:1 correspondence with each other.
+  --
+  -> (Bool,LabelMap lb)
+  -- ^ the pair @(match, map)@ where @match@ is @True@ if the supplied
+  --   sets of arcs can be matched, in which case @map@ is a
+  --   corresponding map from labels to equivalence class identifiers.
+  --   When @match@ is @False@, @map@ is the most detailed equivalence
+  --   class map obtained before a mismatch was detected or a guess
+  --   was required -- this is intended to help identify where the
+  --   graph mismatch may be.
 graphMatch1 guessed matchable gs1 gs2 lmap ecpairs =
     let
         (secs,mecs) = partition uniqueEc ecpairs
         if fst match2 then match2 else (False,lmap)
 -}
 
---  Auxiliary graph matching function
+-- | Auxiliary graph matching function
+--
 --  This function is called when deterministic decomposition of node
 --  mapping equivalence classes has run its course.
 --
         assert (ev1==ev2) "GraphMatch2: Equivalence class value mismatch" $
         try glp
 
-----------------------
---  LabelMap functions
-----------------------
-
-----------------
---  showLabelMap
-----------------
+-- | Returns a string representation  of a LabelMap value
 --
---  Returns a string representation  of a LabelMap value
-
 showLabelMap :: (Label lb) => LabelMap lb -> String
 showLabelMap (LabelMap gn lmap) =
     "LabelMap gen="++ Prelude.show gn ++", map="++
     where
         es = listLookupMap lmap
 
------------------
---  mapLabelIndex
------------------
+-- | Map a label to its corresponding label index value in the supplied LabelMap
 --
---  Map a label to its corresponding label index value in the supplied LabelMap
-
 mapLabelIndex :: (Label lb) => LabelMap lb -> lb -> LabelIndex
 mapLabelIndex (LabelMap _ lxms) lb = mapFind nullLabelVal lb lxms
 
---------------
---  labelMatch
---------------
+-- | Confirm that a given pair of labels are matchable, and are
+--  mapped to the same value by the supplied label map
 --
---  Confirm that a given pair of labels are matchable, and are
---  mapped to the same value by the supplied label map
-
 labelMatch :: (Label lb)
     =>  (lb -> lb -> Bool) -> LabelMap lb -> lb -> lb -> Bool
 labelMatch matchable lmap l1 l2 =
     matchable l1 l2 && (mapLabelIndex lmap l1 == mapLabelIndex lmap l1)
 
----------------
---  newLabelMap
----------------
---
---  Replace selected values in a label map with new values from the supplied
+-- | Replace selected values in a label map with new values from the supplied
 --  list of labels and new label index values.  The generation number is
 --  supplied from the current label map.  The generation number in the
 --  resulting label map is incremented.
-
+--
 newLabelMap :: (Label lb) => LabelMap lb -> [(lb,Int)] -> LabelMap lb
 newLabelMap (LabelMap g f) [] = LabelMap (g+1) f -- new generation
 newLabelMap lmap (lv:lvs)     = setLabelHash (newLabelMap lmap lvs) lv
 
-----------------
---  setLabelHash
-----------------
---
---  setLabelHash replaces a label and its associated value in a label map
+-- | Replace a label and its associated value in a label map
 --  with a new value using the supplied hash value and the current
---  LabelMap generation number.  If the key is not found, then no change
+--  `LabelMap` generation number.  If the key is not found, then no change
 --  is made to the label map.
 
 setLabelHash :: (Label lb)
 setLabelHash  (LabelMap g lmap) (lb,lh) =
     LabelMap g ( mapReplaceAll lmap $ newEntry (lb,(g,lh)) )
 
---------------------
---  newGenerationMap
---------------------
+-- | Increment the generation of the label map.
 --
---  Increment generation of label map.
 --  Returns a new label map identical to the supplied value
 --  but with an incremented generation number.
-
+--
 newGenerationMap :: (Label lb) => LabelMap lb -> LabelMap lb
 newGenerationMap (LabelMap g lvs) = LabelMap (g+1) lvs
 
-------------------
---  assignLabelMap
-------------------
---
---  Scan label list, assigning initial label map values,
+-- | Scan label list, assigning initial label map values,
 --  adding new values to the label map supplied.
 --
 --  Label map values are assigned on the basis of the
 --  label alone, without regard for it's connectivity in
---  the graph.  (cf. reClassify)
+--  the graph.  (cf. `reclassify`).
 --
 --  All variable node labels are assigned the same initial
 --  value, as they may be matched with each other.
-
+--
 assignLabelMap :: (Label lb) => [lb] -> LabelMap lb -> LabelMap lb
 assignLabelMap ns lmap = foldl (flip assignLabelMap1) lmap ns
 
 hashVal seed lab =
     if labelIsVar lab then hash seed "???" else labelHash seed lab
 
-----------------------
---  equivalenceClasses
-----------------------
---
---  lmap    label map
---  ls      list of nodes to be reclassified
---
---  return  list of equivalence classes of the supplied labels under
---          the supplied label map.
-
-equivalenceClasses :: (Label lb) => LabelMap lb -> [lb] -> [EquivalenceClass lb]
+equivalenceClasses :: 
+  (Label lb) 
+  => LabelMap lb -- ^ label map
+  -> [lb]        -- ^ list of nodes to be reclassified
+  -> [EquivalenceClass lb]
+  -- ^ the equivalence classes of the supplied labels under the
+  --   supplied label map
 equivalenceClasses lmap ls =
     pairGroup $ map labelPair ls
     where
         labelPair l = (mapLabelIndex lmap l,l)
 
---------------
---  reclassify
---------------
---
---  Reclassify labels
+-- | Reclassify labels
 --
 --  Examines the supplied label equivalence classes (based on the supplied
 --  label map), and evaluates new equivalence subclasses based on node
 --  Note, assumes that all all equivalence classes supplied are
 --  non-singletons;  i.e. contain more than one label.
 --
---  gs1     is the first of two lists of arcs (triples) to perform a
---          basis for reclassifying the labels in the first equivalence
---          class in each pair of 'ecpairs'.
---  gs2     is the second of two lists of arcs (triples) to perform a
---          basis for reclassifying the labels in the second equivalence
---          class in each pair of 'ecpairs'.
---  lmap    is a label map used for classification of the labels in
---          the supplied equivalence classes.
---  ecpairs a list of pairs of corresponding equivalence classes of
---          nodes from gs1 and gs2 that have not been confirmed
---          in 1:1 correspondence with each other.
---
---  return  a quadruple of:
---          (a) a revised label map reflecting the reclassification,
---          (b) a new list of equivalence class pairs based on the
---          new node map, and
---          (c) if the reclassification partitions any of the
---          supplied equivalence classes then True, else False.
---          any of the supplied equivalence classes
---          (d) if reclassification results in each equivalence class
---          being split same-sized equivalence classes in the two graphs,
---          then True, otherwise False.
+reclassify :: 
+  (Label lb) 
+  => [Arc lb] 
+  -- ^ (the @gs1@ argument) the first of two lists of arcs (triples) to perform a
+  --   basis for reclassifying the labels in the first equivalence
+  --   class in each pair of @ecpairs@.
+  -> [Arc lb]
+  -- ^ (the @gs2@ argument) the second of two lists of arcs (triples) to perform a
+  --   basis for reclassifying the labels in the second equivalence
+  --   class in each pair of the @ecpairs@ argument
+  -> LabelMap lb 
+  -- ^ the label map used for classification of the labels in
+  --   the supplied equivalence classes
+  -> [(EquivalenceClass lb,EquivalenceClass lb)]
+  -- ^ (the @ecpairs@ argument) a list of pairs of corresponding equivalence classes of
+  --   nodes from @gs1@ and @gs2@ that have not been confirmed
+  --   in 1:1 correspondence with each other.
+  -> (LabelMap lb,[(EquivalenceClass lb,EquivalenceClass lb)],Bool,Bool)
+  -- ^ The output tuple consists of:
+  --
+  --  1) a revised label map reflecting the reclassification
+  --
+  --  2) a new list of equivalence class pairs based on the
+  --   new node map
+  --
+  --  3) if the reclassification partitions any of the
+  --     supplied equivalence classes then `True`, else `False`
+  --
+  --  4) if reclassification results in each equivalence class
+  --     being split same-sized equivalence classes in the two graphs,
+  --     then `True`, otherwise `False`.
 
-reclassify :: (Label lb) =>
-    [Arc lb] -> [Arc lb]
-    -> LabelMap lb -> [(EquivalenceClass lb,EquivalenceClass lb)]
-    -> (LabelMap lb,[(EquivalenceClass lb,EquivalenceClass lb)],Bool,Bool)
 reclassify gs1 gs2 lmap@(LabelMap _ lm) ecpairs =
     assert (gen1==gen2) "Label map generation mismatch"
       (LabelMap gen1 lm',ecpairs',newPart,matchPart)
         remapEc ec = pairGroup $ map (newIndex lm') $ pairUngroup ec
         newIndex x (_,lab) = (mapFind nullLabelVal lab x,lab)
 
----------------
---  remapLabels
----------------
---
---  Calculate a new index value for a supplied list of labels based on the
+-- | Calculate a new index value for a supplied list of labels based on the
 --  supplied label map and adjacency calculations in the supplied graph
 --
---  gs      is a list of Arcs used for adjacency calculations when remapping
---  lmap    is a label map used for obtaining current label index values
---  ls      is a list of graph labels for which new mappings are to be
---          created and returned.
---  return  a new label map containing recalculated label index values
---          for the labels in ls.  The label map generation number is
---          incremented by 1 from the supplied 'lmap' value.
-
-remapLabels :: (Label lb) =>
-    [Arc lb] -> LabelMap lb -> [lb] -> LabelMap lb
+remapLabels :: 
+  (Label lb) 
+  => [Arc lb] -- ^ arcs used for adjacency calculations when remapping
+  -> LabelMap lb -- ^ the current label index values
+  -> [lb] -- ^ the graph labels for which new mappings are to be created
+  -> LabelMap lb
+  -- ^ the updated label map containing recalculated label index values
+  -- for the given graph labels. The label map generation number is
+  -- incremented by 1.
 remapLabels gs lmap@(LabelMap gen _) ls =
     LabelMap gen' (LookupMap newEntries)
     where
         mapAdjacent l       = sum (sigsOver l) `rem` hashModulus
         sigsOver l          = select (hasLabel l) gs (arcSignatures lmap gs)
 
------------------------------
---  Graph auxiliary functions
------------------------------
-
----------------
---  graphLabels
----------------
---
---  Return list of distinct labels used in a graph
+-- | Return list of distinct labels used in a graph
 
 graphLabels :: (Label lb) => [Arc lb] -> [lb]
 graphLabels gs = nub $ concatMap arcLabels gs
 
 -- addSetElem ::  lb -> [lb] -> [lb]
 
------------------
---  arcSignatures
------------------
+-- | Calculate a signature value for each arc that can be used in constructing an
+--   adjacency based value for a node.  The adjacancy value for a label is obtained
+--   by summing the signatures of all statements containing that label.
 --
---  Calculate a signature value for each arc that can be used in constructing an
---  adjacency based value for a node.  The adjacancy value for a label is obtained
---  by summing the signatures of all statements containing that label.
---
---  lmap    is a label map used for obtaining current label index values
---  gs      is the list of arcs for which signaturews are calculated
---  return  a list of signature values in correspondence with gs
-
-arcSignatures :: (Label lb) => LabelMap lb -> [Arc lb] -> [Int]
+arcSignatures :: 
+  (Label lb) 
+  => LabelMap lb -- ^ the current label index values
+  -> [Arc lb] -- ^ calculate signatures for these arcs
+  -> [Int] -- ^ the signatures of the arcs
 arcSignatures lmap gs =
     map (sigCalc . arcToTriple) gs
     where
         labelVal         = mapLabelIndex lmap
         labelVal2        = uncurry (*) . labelVal
 
-------------
---  graphMap
-------------
---
---  Return new graph that is supplied graph with every node/arc
+-- | Return a new graph that is supplied graph with every node/arc
 --  mapped to a new value according to the supplied function.
 --
 --  Used for testing for graph equivalence under a supplied
 --  label mapping;  e.g.
 --
---    if ( graphMap nodeMap gs1 ) `equiv` ( graphMap nodeMap gs2 ) then (same)
-
+--  >  if ( graphMap nodeMap gs1 ) `equiv` ( graphMap nodeMap gs2 ) then (same)
+--
 graphMap :: (Label lb) => LabelMap lb -> [Arc lb] -> [Arc LabelIndex]
 graphMap = map . fmap . mapLabelIndex  -- graphMapStmt
 
---------------
---  graphMapEq
---------------
---
---  Compare a pair of graphs for equivalence under a given mapping
---  function.
+-- | Compare a pair of graphs for equivalence under a given mapping
+--   function.
 --
 --  This is used to perform the ultimate test that two graphs are
---  indeed equivalent:  guesswork in graphMatch2 means that it is
+--  indeed equivalent:  guesswork in `graphMatch2` means that it is
 --  occasionally possible to construct a node mapping that generates
 --  the required singleton equivalence classes, but does not fully
 --  reflect the topology of the graphs.

Swish/RDF/GraphMem.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  DeriveFunctor, DeriveFoldable, DeriveTraversable, FlexibleInstances, MultiParamTypeClasses
 --
 --  This module defines a simple memory-based graph instance.
 --
 import qualified Data.Foldable as F
 import qualified Data.Traversable as T
 
------------------------------------------------------
---  Memory-based graph type and graph class functions
------------------------------------------------------
+-- | Memory-based graph type 
 
 data GraphMem lb = GraphMem { arcs :: [Arc lb] }
                    deriving (Functor, F.Foldable, T.Traversable)
 toGraph as = GraphMem { arcs=nub as }
 -}
 
------------
---  graphEq
------------
---
---  Return Boolean graph equality
+-- |  Return Boolean graph equality
 
 graphEq :: (Label lb) => GraphMem lb -> GraphMem lb -> Bool
 graphEq g1 g2 = fst ( matchGraphMem g1 g2 )
 
------------------
---  matchGraphMem
------------------
---
---  GraphMem matching function accepting GraphMem value and returning
+-- | GraphMem matching function accepting GraphMem value and returning
 --  node map if successful
 --
---  g1      is the first of two graphs to be compared
---  g2      is the second of two graphs to be compared
---
---  returns a label map that maps each label to an equivalence
---          class identifier, or Nothing if the graphs cannot be
---          matched.
-
-matchGraphMem :: (Label lb) => GraphMem lb -> GraphMem lb
-                            -> (Bool,LabelMap (ScopedLabel lb))
+matchGraphMem ::
+  (Label lb)
+  => GraphMem lb 
+  -> GraphMem lb
+  -> (Bool,LabelMap (ScopedLabel lb))
+  -- ^ if the first element is @True@ then the second value is a label
+  --   map that maps each label to an equivalence-class identifier,
+  --   otherwise `emptyMap`.
+  --
 matchGraphMem g1 g2 =
     let
         gs1     = arcs g1
     in
         graphMatch matchable gs1 gs2
 
----------------
---  graphBiject
----------------
---
---  Return bijection between two graphs, or empty list
 {-
+-- |  Return bijection between two graphs, or empty list
 graphBiject :: (Label lb) => GraphMem lb -> GraphMem lb -> [(lb,lb)]
 graphBiject g1 g2 = if null lmap then [] else zip (sortedls g1) (sortedls g2)
     where
             | otherwise = compare g1 g2
 -}
 
-------------------------------------------------------------
---  Minimal graph label value - for testing
-------------------------------------------------------------
+-- |  Minimal graph label value - for testing
 
 data LabelMem
     = LF String

Swish/RDF/GraphPartition.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains functions for partitioning a graph into subgraphs

Swish/RDF/MapXsdInteger.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines the datatytpe mapping and relation values

Swish/RDF/N3Formatter.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module implements a Notation 3 formatter (see [1], [2] and [3]),

Swish/RDF/N3Parser.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module implements a Notation 3 parser (see [1], [2], [3]), returning a

Swish/RDF/NTFormatter.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module implements a NTriples formatter (see [1])

Swish/RDF/NTParser.hs

 --  License     :  GPL V2
 --
 --  Maintainer  :  Douglas Burke
---  Stability   :  provisional
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module implements a NTriples parser (see [1]), returning a

Swish/RDF/Proof.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines a framework for constructing proofs

Swish/RDF/RDFDatatype.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines the structures used by Swish to represent and

Swish/RDF/RDFDatatypeXsdInteger.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines the structures used by swish to represent and

Swish/RDF/RDFDatatypeXsdString.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines the structures used by swish to represent and

Swish/RDF/RDFGraph.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  FlexibleInstances, MultiParamTypeClasses, TypeSynonymInstances
 --
 --  This module defines a memory-based RDF graph instance.
 --
 import Data.Ord (comparing)
 
 -----------------------------------------------------------
---  RDF graph node values
-------------------------------------------------------------
+-- | RDF graph node values
 --
---  cf. http://www.w3.org/TR/rdf-concepts/#section-Graph-syntax
+--  cf. <http://www.w3.org/TR/rdf-concepts/#section-Graph-syntax>
 --
 --  This is extended from the RDF abstract graph syntax in the
 --  following ways:
+--
 --  (a) a graph can be part of a resource node or blank node
 --      (cf. Notation3 formulae)
---  (b) a "variable" node option is distinguished from a
+--
+--  (b) a \"variable\" node option is distinguished from a
 --      blank node.
 --      I have found this useful for encoding and handling
 --      queries, even though query variables can be expressed
 --      as blank nodes.
---  (c) a "NoNode" option is defined.
---      This might otherwise be handled by Maybe (RDFLabel g)
+--
+--  (c) a \"NoNode\" option is defined.
+--      This might otherwise be handled by @Maybe (RDFLabel g)@.
+--
 
 -- TODO: should Lit be split up so that can easily differentiate between
 -- a type and a language tag
 
 data RDFLabel =
-      Res ScopedName                    -- resource
-    | Lit String (Maybe ScopedName)     -- literal [type/language]
-    | Blank String                      -- blank node
-    | Var String                        -- variable (not used in ordinary graphs)
-    | NoNode                            -- no node  (not used in ordinary graphs)
+      Res ScopedName                    -- ^ resource
+    | Lit String (Maybe ScopedName)     -- ^ literal [type/language]
+    | Blank String                      -- ^ blank node
+    | Var String                        -- ^ variable (not used in ordinary graphs)
+    | NoNode                            -- ^ no node  (not used in ordinary graphs)
 
 instance Eq RDFLabel where
     (==) = labelEq
     makeLabel  loc          = Blank loc
     labelHash seed lb       = hash seed (showCanon lb)
 
---  Get canonical string for RDF label.
+-- | Get the canonical string for RDF label.
+--
 --  Used for hashing, so that equivalent labels always return
 --  the same hash value.
+    
 showCanon :: RDFLabel -> String
 showCanon (Res sn)           = "<"++getScopedNameURI sn++">"
 showCanon (Lit st (Just nam))
 showCanon s                  = show s
 
 
--- Define equality of nodes possibly based on different graph types.
+-- | Define equality of nodes possibly based on different graph types.
 --
 -- The version of equality defined here is not strictly RDF abstract syntax
 -- equality, but my interpretation of equivalence for the purposes of
 makeBlank  (Var loc)    = Blank loc
 makeBlank  lb           = lb
 
----------------------------------------------------------
---  RDF Triple (statement)
----------------------------------------------------------
+-- | RDF Triple (statement)
 
 type RDFTriple = Arc RDFLabel
 
----------------------------------------------------------
---  Namespace prefix list entry
----------------------------------------------------------
+-- | Namespace prefix list entry
 
 type NamespaceMap = LookupMap Namespace
 
 emptyNamespaceMap :: NamespaceMap
 emptyNamespaceMap = LookupMap []
 
----------------------------------------------------------
---  Graph formula entry
----------------------------------------------------------
+-- | Graph formula entry
 
 data LookupFormula lb gr = Formula
     { formLabel :: lb
     
 -}
 
----------------------------------------------------------
---  Memory-based graph with namespaces and subgraphs
----------------------------------------------------------
+-- | Memory-based graph with namespaces and subgraphs
 
 data NSGraph lb = NSGraph
     { namespaces :: NamespaceMap
         , formulae   = LookupMap []
         }
 
----------------------------------------------------------
---  Merge RDF graphs, renaming bnodes in the second graph
---  as necessary
----------------------------------------------------------
-
 -- |Merge RDF graphs, renaming blank and query variable nodes as
 --  needed to neep variable nodes from the two graphs distinct in
 --  the resulting graph.
 allNodes :: (Label lb) => (lb -> Bool) -> NSGraph lb -> [lb]
 allNodes p = unionNodes p [] . nodes
 
---  List all nodes in graph formulae satisfying a supplied predicate
+-- | List all nodes in graph formulae satisfying a supplied predicate
 formulaNodes :: (Label lb) => (lb -> Bool) -> NSGraph lb -> [lb]
 formulaNodes p gr = foldl (unionNodes p) fkeys (map (allLabels p) fvals)
     where
         -- fkeys :: (Label lb) => [lb]
         fkeys = filter p $ mapKeys fm
 
---  Helper to filter variable nodes and merge with those found so far
+-- | Helper to filter variable nodes and merge with those found so far
 unionNodes :: (Label lb) => (lb -> Bool) -> [lb] -> [lb] -> [lb]
 unionNodes p ls1 ls2 = ls1 `union` filter p ls2
 
----------------------------------------------------------
---  Remap selected nodes in a graph
----------------------------------------------------------
-
 -- |Remap selected nodes in graph:
 --
 --  This is the node renaming operation that prevents graph-scoped
     -> [(lb,lb)]
 remapLabelList remap avoid = maplist remap avoid id []
 
---  Remap a single graph node.
+-- | Remap a single graph node.
+--
 --  If the node is not one of those to be remapped,
 --  the supplied value is returned unchanged.
 mapnode ::
 mapnode dupbn allbn cnvbn nv =
     mapFind nv nv (LookupMap (maplist dupbn allbn cnvbn []))
 
---  Construct a list of (oldnode,newnode) values to be used for
+-- | Construct a list of (oldnode,newnode) values to be used for
 --  graph label remapping.  The function operates recursiovely, adding
 --  new nodes generated to the mapping list (mapbn') and also to the
 --  list of nodes to be avoided (allbn').
 trybnodes (nr,nx) = [ makeLabel (nr++show n) | n <- iterate (+1) nx ]
 -}
 
----------------------------------------------------------
---  Memory-based RDF graph type and graph class functions
----------------------------------------------------------
+-- | Memory-based RDF graph type
 
 type RDFGraph = NSGraph RDFLabel
 

Swish/RDF/RDFGraphShowM.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98 + ????
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  TypeSynonymInstances
 --
---  This module defines a ShowM class instance for RDFGraph, to be
+--  This module defines a `ShowM` class instance for `RDFGraph`, to be
 --  used when displaying RDF Graph values as part of a proof sequence,
 --  etc.
 --

Swish/RDF/RDFParser.hs

 --  License     :  GPL V2
 --
 --  Maintainer  :  Douglas Burke
---  Stability   :  provisional
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  Support for the RDF Parsing modules.

Swish/RDF/RDFProof.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98 + multi-parameter classes
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  FlexibleInstances, UndecidableInstances
 --
 --  This module instantiates the 'Proof' framework for
 --  constructing proofs over RDFGraph expressions.

Swish/RDF/RDFProofContext.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains proof-context declarations based on

Swish/RDF/RDFQuery.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines functions for querying an RDF graph to obtain

Swish/RDF/RDFRuleset.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines some datatypes and functions that are

Swish/RDF/RDFVarBinding.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module instantiates the `VarBinding` types and methods for use

Swish/RDF/Rule.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  MultiParamTypeClasses
 --
 --  This module defines a framework for defining inference rules
     newEntry (_,form) = form
     keyVal form = (formName form, form)
 
+-- | The namespace @http://id.ninebynine.org/2003/Ruleset/null@
 nullScope :: Namespace
 nullScope = Namespace "null" "http://id.ninebynine.org/2003/Ruleset/null"
 

Swish/RDF/Ruleset.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  MultiParamTypeClasses
 --
 --  This module defines a ruleset data type, used to collect information
 --  about a ruleset that may contribute torwards inferences in RDF;
 import Data.Maybe
     ( fromMaybe, listToMaybe, mapMaybe )
 
-------------------------------------------------------------
---  Ruleset, having namespace, axioms and rules
-------------------------------------------------------------
+-- | Ruleset, having namespace, axioms and rules
 
 data Ruleset ex = Ruleset
     { rsNamespace :: Namespace
 getRulesetRules :: Ruleset ex -> [Rule ex]
 getRulesetRules = rsRules
 
-------------------------------------------------------------
---  Find a named axiom or rule in a ruleset or proof context
-------------------------------------------------------------
+-- | Find a named axiom or rule in a ruleset or proof context
 
 getRulesetAxiom :: ScopedName -> Ruleset ex -> Maybe (Formula ex)
 getRulesetAxiom nam rset =

Swish/RDF/SwishCommands.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  SwishCommands:  functions to deal with indivudual Swish command options.

Swish/RDF/SwishMain.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  Swish:  Semantic Web Inference Scripting in Haskell

Swish/RDF/SwishMonad.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  FlexibleInstances and MultiParamTypeClasses
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  FlexibleInstances, MultiParamTypeClasses
 --
---  SwishMonad:  Composed state and IO monad for Swish
+--  Composed state and IO monad for Swish
 --
 --------------------------------------------------------------------------------
 
 
 import System.IO (hPutStrLn, stderr)
 
-------------------------------------------------------------
---  State and state monad for Swish program
-------------------------------------------------------------
---
---  Uses StateT Monad transformer:
---  See example by Mark Carroll at http://www.haskell.org/hawiki/MonadState
-
 {-|
 The supported input and output formats.
 -}
   show NT  = "Ntriples"
   -- show RDF = "RDF/XML"
 
+-- | The State for a Swish \"program\".
+  
 data SwishState = SwishState
     { format    :: SwishFormat      -- ^ format to use for I/O
     , base      :: Maybe QName      -- ^ base to use rather than file name
     , infomsg   = Nothing
     , errormsg  = Nothing
     , exitcode  = SwishSuccess
-    -- , banner = True
     }
 
 setFormat :: SwishFormat -> SwishState -> SwishState
 setVerbose f state = state { banner = f }
 -}
 
-------------------------------------------------------------
---  Data types for Swish script dictionaries
-------------------------------------------------------------
---
---  The graphs dictionary contains named graphs and/or lists
+-- | The graphs dictionary contains named graphs and/or lists
 --  of graphs that are created and used by script statements.
 
 data NamedGraph = NamedGraph
 
 type NamedGraphMap = LookupMap NamedGraph
 
-------------------------------------------------------------
---  Report error and set exit status code
-------------------------------------------------------------
+-- | Report error and set exit status code
 
 swishError :: String -> SwishStatus -> SwishStateIO ()
 swishError msg sts = do
   -- when (sts == 4) $ reportLine "Use 'Swish -h' or 'Swish -?' for help\n"
   modify $ setStatus sts
 
-------------------------------------------------------------
---  Output text to the standard error stream
-------------------------------------------------------------
+-- | Output text to the standard error stream
 --
 --  Each string in the supplied list is a line of text to
 --  be displayed.

Swish/RDF/SwishScript.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module implements the Swish script processor:  it parses a script

Swish/RDF/VarBinding.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  MultiParamTypeClasses, TypeSynonymInstances
 --
 --  This module defines functions for representing and manipulating query
 --  binding variable sets.  This is the key data that mediates between
 
 -- |Variable binding usage compatibility test.
 --
---  bvars   are variables supplied with bindings
---  vocab   are variables returned with bindings by a modifier
---  ovars   are variables assigned new bindings by a modifier
---
---  Returns True if the supplied variable bindings can be compatibly
+--  Returns @True@ if the supplied variable bindings can be compatibly
 --  processed by a variable binding usage with supplied vocabulary and
 --  usage pattern.
 --
-vbmCompatibleVars :: (Eq a) => [a] -> [a] -> [a] -> Bool
+vbmCompatibleVars ::
+  (Eq a) 
+  => [a] -- ^ variables supplied with bindings
+  -> [a] -- ^ variables returned with bindings by a modifier
+  -> [a] -- ^ variables assigned new bindings by a modifier
+  -> Bool
 vbmCompatibleVars bvars vocab ovars =
     null (ivars `intersect` ovars) &&       -- ivars and ovars don't overlap
     null ((vocab \\ ovars) \\ ivars)        -- ovars and ivars cover vocab

Swish/RDF/Vocabulary.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines some commonly used vocabulary terms,

Swish/Utils/DateTime.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module defines a collection of date/time manipulation functions. It

Swish/Utils/ListHelpers.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines some generic list and related helper functions.

Swish/Utils/LookupMap.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98, class dependencies
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  A lot of LANGUAGE extensions...
 --
 --  This module defines a lookup table format and associated functions
 --  used by the graph matching code.
 emptyLookupMap :: (LookupEntryClass a k v) => LookupMap a
 emptyLookupMap = LookupMap []
 
--- |Function to create a 'LookupMap' from a list of entries.
+-- |Function to create a `LookupMap` from a list of entries.
 --
 --  Currently, this is trivial but future versions could be
 --  more substantial.
                         then emap
                         else mapCons e emap
 
--- ADelete supplied key value from the lookup map.
+-- |Delete supplied key value from the lookup map.
+--
 --  This function assumes exactly one occurrence.
 --
 mapDelete :: (LookupEntryClass a k v) =>
 mapTranslateEntries :: (a1 -> a2) -> LookupMap a1 -> LookupMap a2
 mapTranslateEntries = fmap
 
--- |A monadic form of 'mapTranslateEntries'
+-- |A monadic form of `mapTranslateEntries`.
 --
--- Since 'LookupMap' now has a 'Data.Traversable.Traversable' instance
--- this is just 'Data.Traversable.mapM'.
+-- Since `LookupMap` now has a `Data.Traversable.Traversable` instance
+-- this is just `T.mapM`.
 --
 mapTranslateEntriesM :: (Monad m)
     => (a1 -> m a2) -> LookupMap a1 -> m (LookupMap a2)

Swish/Utils/MiscHelpers.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines some generic list and related helper functions

Swish/Utils/Namespace.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  TypeSynonymInstances, MultiParamTypeClasses
 --
 --  This module defines algebraic datatypes for namespaces and scoped names.
 --
 import Swish.Utils.LookupMap
     ( LookupEntryClass(..) )
 
-{- in Prelude???
-import Maybe
-    ( Maybe(..), fromJust )
--}
-
 ------------------------------------------------------------
 --  Namespace, having a prefix and a URI
 ------------------------------------------------------------

Swish/Utils/PartOrderedCollection.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module provides methods to support operations on partially ordered
 --  collections.  The partial ordering relationship is represented by
---  Maybe Ordering.
+--  Maybe `Ordering`.
 --
---  Thanks to members of the haskell-cafe mailing list:
---    Robert <rvollmert-lists@gmx.net>
---    Tom Pledger <Tom.Pledger@peace.com>
+--  Thanks to members of the haskell-cafe mailing list -
+--    Robert (rvollmert-lists@gmx.net) and
+--    Tom Pledger (Tom.Pledger@peace.com) -
 --  who suggested key ideas on which some of the code in this module is based.
 --
 --------------------------------------------------------------------------------

Swish/Utils/QName.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines an algebraic datatype for qualified names (QNames).

Swish/Utils/ShowM.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines an extension of the Show class for displaying

Swish/Utils/TraceHelpers.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module provides access to tracing functions from the pre-2003
 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module is a wrapper for the main program of Swish.
-Name:                swish
-Version:             0.3.0.0
-Stability:           experimental
-License:             LGPL
-License-file:        LICENSE 
-Author:              Graham Klyne - GK@ninebynine.org
-Copyright:           (c) 2003, 2004 G. Klyne; 2009 Vasili I Galchin; 2011 Doug Burke; All rights reserved.
-Maintainer:          dburke@cfa.harvard.edu
-Homepage:            https://bitbucket.org/doug_burke/swish
-Bug-reports:         https://bitbucket.org/doug_burke/swish/issues
+Name:               swish
+Version:            0.3.0.0
+Stability:          experimental
+License:            LGPL
+License-file:       LICENSE 
+Author:             Graham Klyne - GK@ninebynine.org
+Copyright:          (c) 2003, 2004 G. Klyne; 2009 Vasili I Galchin; 2011 Doug Burke; All rights reserved.
+Maintainer:         dburke@cfa.harvard.edu
+Category:           Semantic Web
+Synopsis:           A semantic web toolkit. 
 
-Category:            Semantic Web
-Synopsis:            A semantic web toolkit. 
+Tested-With:        GHC==6.12.3
+Cabal-Version:      >= 1.6
+Homepage:           https://bitbucket.org/doug_burke/swish/wiki/Home
+Bug-reports:        https://bitbucket.org/doug_burke/swish/issues
+
 Description:        Swish is a framework, written in the purely functional 
                     programming language Haskell, for performing deductions in 
                     RDF data using a variety of techniques. Swish is conceived 
                     .
                     * Complete, ready-to-run, command-line and script-driven programs.
                     .
-                    ChangeLog:
+                    Major Changes:
                     .
                     [Version 0.3.0.0] is an attempt to update 
                     version 0.2.1 (<http://hackage.haskell.org/package/swish-0.2.1/>)
                       - CWM: <http://www.w3.org/2000/10/swap/doc/cwm.html>
                     .
 
-Tested-With:         GHC==6.12.3
-Build-Type:          Simple
-Data-Files:          README
+Build-Type:         Simple
+Data-Files:         README
 
-Cabal-Version:       >= 1.6
+Source-repository head
+  type:     mercurial
+  location: https://bitbucket.org/doug_burke/swish
 
 Flag  tests
   Description: Build the test programs.
   Description: Use Hpc for the tests
   Default:     False
 
+
 Library
    Build-Depends:
       base >=3 && < 5,

tests/BuiltInMapTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for accessing built-in variable

tests/GraphPartitionTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for graph partitioning logic.

tests/GraphTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98 + multi-parameter classes
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  H98
 --
 --  This module defines test cases for module Graph.
 --

tests/LookupMapTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  FlexibleInstances, FlexibleContexts, MultiParamTypeClasses
 --
 -- This Module defines test cases for module Parse parsing functions.
 --

tests/N3FormatterTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module defines test cases for module Parse parsing functions.

tests/N3ParserTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module contains test cases for module "N3Parser".
 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This Module contains test cases for the NTriples modules: 

tests/QNameTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module defines test cases for QName data

tests/RDFDatatypeXsdIntegerTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for variable binding values and

tests/RDFGraphTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for module RDFGraph.

tests/RDFProofContextTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains RDF proof-checking test cases based on the RDF

tests/RDFProofTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module tests the RDFproof module, which instantiates the proof

tests/RDFQueryTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
---  Portability :  H98 + multi-parameter classes
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
+--  Portability :  H98
 --
 --  This module defines test cases for querying an RDF graph to obtain
 --  a set of variable substitutions, and to apply a set of variable

tests/RDFRulesetTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for ruleset data.

tests/SwishTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  SwishTest:  Test cases for Swish program.

tests/VarBindingTest.hs

 --  Copyright   :  (c) 2003, Graham Klyne, 2009 Vasili I Galchin, 2011 Douglas Burke
 --  License     :  GPL V2
 --
---  Maintainer  :  Graham Klyne
---  Stability   :  provisional
+--  Maintainer  :  Douglas Burke
+--  Stability   :  experimental
 --  Portability :  H98
 --
 --  This module contains test cases for variable binding values and