Doc tool enhancements, get documentations error free

Author: Ingo60

frege/PreludeProperties.fr

@@ -44,7 +44,8 @@ package frege.PreludeProperties where
 import Data.List 
 
 import frege.prelude.Math (floor)
-import Test.QuickCheck
+-- import Test.QuickCheckArbitrary ()
+import Test.QuickCheck 
 
 trivial = (`classify` "trivial")
 

frege/compiler/Classes.fr

@@ -477,7 +477,7 @@ funForCIT cname iname tname (mname@MName _ base) = do
                                         expr = mbx,
                                         typ = U.pSigma, anno = false, exported = false,
                                         state = Unchecked, sid = 0,
-                                        doc = Just ("inherited from '" ++ xname.nice g ++ "'")}
+                                        doc = Just ("inherited from '" ++ xname.nicer g ++ "'")}
                         U.enter imem
                         U.linkq (MName tname base) imem
                     else if cname.our g || mem.vis == Abstract then
@@ -488,7 +488,7 @@ funForCIT cname iname tname (mname@MName _ base) = do
                                         typ = U.pSigma, anno = false, exported = false,
                                         state = Unchecked,
                                         sid = 0,
-                                        doc = Just ("uses '" ++ xname.nice g ++ "'"),
+                                        doc = Just ("uses '" ++ xname.nicer g ++ "'"),
                                         expr = Just (Vbl isym.pos xname Nothing)}
                         U.enter imem
                         U.linkq (MName tname base) imem

frege/compiler/Data.fr

@@ -378,6 +378,7 @@ data QName =
         nicer (Local {uid, base}) g = base
         nicer (qn@TName p s) g
             | findit qn g == findit (TName g.thisPack s) g = s
+        nicer    (MName t s)    g = t.nicer g ++ "." ++ s
         nicer  qn g = nice qn g
         --- tell if this is the name of a let or lambda bound item
         isLocal (Local{}) = true

frege/compiler/DocUtils.fr

@@ -199,10 +199,12 @@ docSym g (SymT {name, doc, typ=ForAll _ rho, env, nativ, pur, mutable}) = (code
                                 DL (Just "func") (map (docSym g) members)]],
                     p <- d ]
 
-docSym g (SymD {name, doc, typ, flds}) = (code title, docit g doc) where
-    title = label name
+docSym g (SymD {name, doc, typ, vis, flds}) = (code title, docit g doc) where
+    title = lbl             -- label name
         :- text " "
         :- typeorfields
+    lbl | vis == Public = label name
+        | otherwise     = (bold . text) (show vis) :- text " " :- label name 
     typeorfields = if (all (isJust • ConField.name) flds && not (null flds)) then fields else types
     fields = text "{" :- joint ", " fsmap flds :- text "}"
     types  = joins 2 (drho • ConField.typ) flds
@@ -223,6 +225,8 @@ docSym g (SymV {name, typ, doc, nativ, pur, strsig, throwing}) = (code title, do
 
 docSym g (SymL {name,alias}) = case alias.findit g of
     Nothing -> (badref (name.nice g ++ "links to " ++ alias.nice g ++ " but not found"), [])
+    Just (vsym@SymV{})  = docSym g vsym.{name, 
+                                doc = Just ("Alias for '" ++ name.base ++ "'")}
     Just sym -> docSym g sym
 
 --- create a label  for a variable or a constructor

frege/control/Concurrent.fr

@@ -3,7 +3,7 @@
     
     Concurrency in Frege comes in 2 flavors. 
     The first is through 'Thread's, which are,
-    unlike in Haskell, @OS@ threads.
+    unlike in Haskell, _OS threads_.
   
     The second possibility is to use a thread pool and an executor service 
     one can submit tasks to. But note that blocking asynchronous tasks,
@@ -14,8 +14,10 @@ module frege.control.Concurrent where
 
 import frege.java.util.Concurrent as C
 
---- A thread safe, shared variable, that is either full or empty.    
-abstract data MVar a = MV (BlockingQueue a) where
+--- A thread safe, shared variable, that is either full or empty.
+--- Technically, this is just a 'BlockingQueue' restricted to length 1.    
+abstract data MVar a  =  MV (BlockingQueue a) where
+    
     --- create an empty 'MVar'
     newEmpty        = ArrayBlockingQueue.new 1 >>= return . MV
 
@@ -31,7 +33,7 @@ abstract data MVar a = MV (BlockingQueue a) where
     --- put a value in a 'MVar', returns false if already full.
     offer (MV q) a  = q.offer a
 
-    --- get the value from a 'MVar', return 'Nothing' is empty
+    --- get the value from a 'MVar', return 'Nothing' when empty
     poll  (MV q)    = q.poll  
 
 -- Haskell compatibility
@@ -42,7 +44,7 @@ tryPutMVar      = MVar.offer
 
 
 --- Create and start a new OS 'Thread' that runs an 'IO' action.
---- In Frege, there is no difference between 'forkIO' and 'forkOS' 
+--- In Frege, there is no difference between 'forkIO' and 'frege.control.Concurrent#forkOS' at this time. 
 forkIO :: IO () -> IO Thread
 forkIO action = do
     r <- Runnable.new action

frege/data/Traversable.fr

@@ -92,7 +92,7 @@ protected instance Applicative (StateL s) where
         in (s'', f v))
 
 {-- The 'mapAccumL' function behaves like a combination of 'fmap'
-    and 'foldl'; it applies a function to each element of a structure,
+    and 'fold'; it applies a function to each element of a structure,
     passing an accumulating parameter from left to right, and returning
     a final value of this accumulator together with the new structure.
     -}

frege/data/TreeMap.fr

@@ -324,6 +324,7 @@ intersection s1 s2 = (Tree.insertList empty . filter ((s2 `contains`) . fst) . T
 diff s1 s2 = (Tree.insertList empty . filter (not . (s2 `contains`) . fst) . Tree.each) s1
 
 import Test.QuickCheck
+import Test.QuickCheckArbitrary ()  -- avoid doc error
 
 instance CoArbitrary (Ord k, CoArbitrary k, CoArbitrary v) => (Tree k v) where
     coarbitrary Tree.Nil = variant 0
@@ -336,7 +337,7 @@ instance Arbitrary (Ord k, Arbitrary k, Arbitrary v) => (Tree k v) where
 aTree = arbitrary :: Gen (Tree Int String)
 aList = arbitrary :: Gen [(Int, String)]
 
---- The empty tree is 'Nil'
+--- The empty tree is 'Tree.Nil'
 p_emptyIsNil = property (nil empty) 
     where 
         nil Tree.Nil = true

frege/java/IO.fr

@@ -107,7 +107,7 @@ native stdin  frege.runtime.Runtime.stdin  :: BufferedReader
     Not intended for direct use but rather as something
     a 'PrintWriter' can be made of. (Though, because
     of the 'Appendable' inheritance, one could 
-    still 'append' directly.)
+    still 'Appendable.append' directly.)
     
     To be used like:
     
@@ -175,7 +175,7 @@ data BufferedReader = mutable native java.io.BufferedReader where
     native new :: Reader -> IO BufferedReader
     {--
         Reads a line of text. A line is considered to be terminated 
-        by any one of a line feed ('\n'), a carriage return ('\r'), 
+        by any one of a line feed ("\n"), a carriage return ("\r"), 
         or a carriage return followed immediately by a linefeed.
         
         [Returns:] 'Just' _string_, where _string_ is the contents of the line, 
@@ -196,7 +196,7 @@ data BufferedReader = mutable native java.io.BufferedReader where
                 _      ->  br.close >> return (reverse acc)
 
     {-- 
-        Reads the next line from a buffered reader using 'readLine', 
+        Reads the next line from a buffered reader using 'BufferedReader.readLine', 
         and returns the string or throws 'EOFException' on end of file. 
         -}       
     getLine :: BufferedReader -> IO String

frege/prelude/PreludeList.fr

@@ -38,7 +38,7 @@
     This package provides common list functions for the Frege language.
     
     It contains all functions described in section 9.1 of the 
-    _Haskell 2010 Language Report_, except for @lookup@, which has been moved 
+    _Haskell 2010 Language Report_, except for 'Data.List#lookup', which has been moved 
     to @frege.data.List@ (the equivalent of Haskell's @Data.List@).
     
     In addition to the common list functions, three type classes capture common
@@ -48,11 +48,7 @@
     ['ListSource'] is the type class for types that can be converted to lists ('toList'). 
     There are instances for 'String', 'Maybe', 'Either' and arrays. 
     
-    The functions 'words' and 'lines' take 'String' arguments and return lists of 'String', 
-    whereas 'unwords' and 'unlines' take an instance of 'ListSource' with 'String' elements
-    and return a single 'String'.
-
-    This package is /implementation specific/ insofar as the compiler may
+    This module is _implementation specific_ insofar as the compiler may
     assume that certain items are defined here in a certain way.
     Changes may thus lead to compiler crashes or java code that 
     will be rejected by the java compiler.

frege/prelude/PreludeText.fr

@@ -1,12 +1,10 @@
--- «•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»«•»
-
 {--
     Classes and Instances to convert values to 'String's ('show') and 'String's to values
-    ('read').
+    ("read").
 
     There are a few differences to Haskell, notably
 
-    - 'Read' cannot be derived and supports only simple types
+    - "Read" cannot be derived and supports only simple types
 -}
 
 protected package frege.prelude.PreludeText where