Doc.icl 18.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
implementation module Clean.Doc

import _SystemArray
import StdBool
import StdChar
import StdDebug
from StdFunc import flip, o, twice
import StdList
import StdMisc
import StdOrdList
import StdString
import StdTuple

import Control.Applicative
15
from Control.Monad import mapM, class Monad(..), >>=
16 17 18 19 20 21 22 23
import Data.Either
import Data.Error
from Data.Func import $
import Data.Functor
import Data.GenDefault
import Data.List
import Data.Maybe
import Data.Tuple
24
from Text import <+,
25
	class Text(join,split,trim,rtrim,replaceSubString,endsWith,startsWith),
26 27 28 29
	instance Text String, instance Text [Char]
import Text.Language
import Text.Parsers.Simple.ParserCombinators

30
from Clean.Types import :: Type, :: TypeRestriction, :: TypeContext
Mart Lubbers's avatar
Mart Lubbers committed
31
from Clean.Types.Parse import parseType
32
from Clean.Types.Util import instance toString Type
33 34 35 36 37 38 39

gDefault{|Maybe|} _ = Nothing

fromMultiLine :: !MultiLineString -> String
fromMultiLine (MultiLine s) = s

instance docDescription       ModuleDoc where docDescription       d = d.ModuleDoc.description
40
instance docPropertyBootstrap ModuleDoc where docPropertyBootstrap d = d.property_bootstrap
41 42 43 44 45 46 47 48 49 50
instance docPropertyTestWith  ModuleDoc where docPropertyTestWith  d = d.ModuleDoc.property_test_with
instance docPropertyTestGenerators ModuleDoc where docPropertyTestGenerators d = d.property_test_generators

instance docDescription      FunctionDoc where docDescription      d = d.FunctionDoc.description
instance docComplexity       FunctionDoc where docComplexity       d = d.FunctionDoc.complexity
instance docParams           FunctionDoc where docParams           d = d.FunctionDoc.params
instance docVars             FunctionDoc where docVars             d = d.FunctionDoc.vars
instance docResults          FunctionDoc where docResults          d = d.FunctionDoc.results
instance docType             FunctionDoc where docType             d = d.FunctionDoc.type
instance docThrows           FunctionDoc where docThrows           d = d.FunctionDoc.throws
51
instance docProperties       FunctionDoc where docProperties       d = d.FunctionDoc.properties
52
instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.FunctionDoc.property_test_with
53 54 55 56 57 58 59
instance docPreconditions    FunctionDoc where docPreconditions    d = d.FunctionDoc.preconditions

instance docDescription      InstanceDoc where docDescription      d = d.InstanceDoc.description
instance docComplexity       InstanceDoc where docComplexity       d = d.InstanceDoc.complexity
instance docProperties       InstanceDoc where docProperties       d = d.InstanceDoc.properties
instance docPropertyTestWith InstanceDoc where docPropertyTestWith d = d.InstanceDoc.property_test_with
instance docPreconditions    InstanceDoc where docPreconditions    d = d.InstanceDoc.preconditions
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88

instance docDescription ParamDoc where docDescription d = d.ParamDoc.description

instance docDescription ClassMemberDoc where docDescription d = d.ClassMemberDoc.description
instance docComplexity  ClassMemberDoc where docComplexity  d = d.ClassMemberDoc.complexity
instance docParams      ClassMemberDoc where docParams      d = d.ClassMemberDoc.params
instance docResults     ClassMemberDoc where docResults     d = d.ClassMemberDoc.results
instance docType        ClassMemberDoc where docType        d = d.ClassMemberDoc.type
instance docThrows      ClassMemberDoc where docThrows      d = d.ClassMemberDoc.throws

instance docDescription ConstructorDoc where docDescription d = d.ConstructorDoc.description
instance docParams      ConstructorDoc where docParams      d = d.ConstructorDoc.params

instance docDescription ClassDoc where docDescription d = d.ClassDoc.description
instance docVars        ClassDoc where docVars        d = d.ClassDoc.vars
instance docMembers     ClassDoc where docMembers     d = d.ClassDoc.members

instance docDescription    TypeDoc where docDescription    d = d.TypeDoc.description
instance docVars           TypeDoc where docVars           d = d.TypeDoc.vars
instance docFields         TypeDoc where docFields         d = d.TypeDoc.fields
instance docConstructors   TypeDoc where docConstructors   d = d.TypeDoc.constructors
instance docRepresentation TypeDoc where docRepresentation d = d.TypeDoc.representation

instance toString ParamDoc
where
	toString pd=:{name=Just n,description=Just d} = n +++ ": " +++ d
	toString {ParamDoc | description=Just d} = d
	toString _ = ""

89
derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, InstanceDoc, TypeContext,
90
	ClassMemberDoc, ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyBootstrapDoc,
91
	PropertyVarInstantiation, MultiLineString, PropertyTestGenerator, ParamDoc
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123

constructorToFunctionDoc :: !ConstructorDoc -> FunctionDoc
constructorToFunctionDoc d =
	{ FunctionDoc
	| gDefault{|*|}
	& description = d.ConstructorDoc.description
	, params      = d.ConstructorDoc.params
	}

functionToClassMemberDoc :: !FunctionDoc -> ClassMemberDoc
functionToClassMemberDoc d =
	{ ClassMemberDoc
	| description = d.FunctionDoc.description
	, complexity  = d.FunctionDoc.complexity
	, params      = d.FunctionDoc.params
	, results     = d.FunctionDoc.results
	, type        = d.FunctionDoc.type
	, throws      = d.FunctionDoc.throws
	}

addClassMemberDoc :: !ClassDoc !(Maybe ClassMemberDoc) -> ClassDoc
addClassMemberDoc d m = {d & members=d.members ++ [m]}

parseSingleLineDoc :: (String -> String)
parseSingleLineDoc = toString o trim o dropWhile ((==) '*') o fromString

parseDoc :: !String -> Either ParseError (!d, ![ParseWarning]) | docBlockToDoc{|*|} d
parseDoc s = docBlockToDoc{|*|} (Left [s])

generic docBlockToDoc d :: !(Either [String] DocBlock) -> Either ParseError (!d, ![ParseWarning])
docBlockToDoc{|String|} (Left []) = Left InternalNoDataError
docBlockToDoc{|String|} (Left ss) = Right (trim $ last ss, [])
Camil Staps's avatar
Camil Staps committed
124
docBlockToDoc{|String|} _         = abort "error in docBlockToDoc{|String|}\n"
125
docBlockToDoc{|[]|} fx (Left ss) = (\vws -> (map fst vws, flatten (map snd vws)) ) <$> mapM fx (map (Left o pure) ss)
Camil Staps's avatar
Camil Staps committed
126 127
docBlockToDoc{|[]|} _  _         = abort "error in docBlockToDoc{|[]|}\n"
docBlockToDoc{|Maybe|} fx (Left [])    = Right (Nothing, [])
128
docBlockToDoc{|Maybe|} fx ss=:(Left _) = appFst Just <$> fx ss
Camil Staps's avatar
Camil Staps committed
129
docBlockToDoc{|Maybe|} _  _            = abort "error in docBlockToDoc{|Maybe|}\n"
130 131
docBlockToDoc{|UNIT|} _ = Right (UNIT, [])
docBlockToDoc{|PAIR|} fx fy db=:(Right _) = liftA2 (\(x,ws) (y,ws`) -> (PAIR x y, ws ++ ws`)) (fx db) (fy db)
Camil Staps's avatar
Camil Staps committed
132 133
docBlockToDoc{|PAIR|} _  _  _             = abort "error in docBlockToDoc{|PAIR|}\n"
docBlockToDoc{|FIELD of {gfd_name}|} fx (Right db) = case fx (Left [v \\ (k,v) <- db | k matches gfd_name]) of
134
	Right (f, ws)            -> Right (FIELD f, ws)
Camil Staps's avatar
Camil Staps committed
135
	Left InternalNoDataError -> Left (MissingField gfd_name)
136 137 138 139 140 141 142 143 144 145
	Left e                   -> Left e
where
	(matches) infix 4 :: !String !String -> Bool
	(matches) k name =
		k` == name ||
		pluralise English k` == name ||
		k` == "return" && name == "result" ||
		k` == "return" && name == "results"
	where
		k` = {if (c == '-') '_' c \\ c <-: k}
Camil Staps's avatar
Camil Staps committed
146
docBlockToDoc{|FIELD of {gfd_name}|} _ _ = abort "error in docBlockToDoc{|FIELD|}\n"
147 148 149 150 151 152 153 154 155 156 157 158
docBlockToDoc{|RECORD|} fx (Left [s]) = case parseDocBlock s of
	Right (db, ws) -> case fx (Right db) of
		Right (v, ws`) -> Right (RECORD v, ws ++ ws`)
		Left e -> Left e
	Left e -> Left e
docBlockToDoc{|RECORD|} fx doc = appFst RECORD <$> fx doc
docBlockToDoc{|CONS|} fx doc = appFst CONS <$> fx doc
docBlockToDoc{|EITHER|} fl fr doc = case fl doc of
	Right (v, ws) -> Right (LEFT v, ws)
	Left e -> case fr doc of
		Right (v, ws) -> Right (RIGHT v, ws)
		Left _ -> Left e
159
docBlockToDoc{|OBJECT|} fx doc = appFst (\x -> OBJECT x) <$> fx doc
160

161
docBlockToDoc{|MultiLineString|} (Left [s]) = Right (MultiLine (trimMultiLine $ split "\n" s), [])
Camil Staps's avatar
Camil Staps committed
162
docBlockToDoc{|MultiLineString|} _          = abort "error in docBlockToDoc{|MultiLineString|}\n"
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

docBlockToDoc{|ParamDoc|} (Left [s]) = case findName (fromString s) of
	Just (name,rest) -> Right (
		{ name        = Just $ toString name
		, description = case rest of
			[] -> Nothing
			_  -> Just $ toString rest
		}, [])
	_                -> Right ({name=Nothing, description=Just s}, [])
where
	findName cs
	# (name,cs) = span (\c -> isAlphanum c || c == '`') cs
	| not (isEmpty name) && not (isEmpty cs) && hd cs == ':'
		= Just (toString name, dropWhile isSpace (tl cs))
		= Nothing
Camil Staps's avatar
Camil Staps committed
178
docBlockToDoc{|ParamDoc|} _ = abort "error in docBlockToDoc{|ParamDoc|}\n"
179 180

docBlockToDoc{|Type|} (Left []) = Left InternalNoDataError
Mart Lubbers's avatar
Mart Lubbers committed
181
docBlockToDoc{|Type|} (Left ss) = case [v \\ Just v <- map (parseType o fromString) ss] of
182 183
	[] -> Left (UnknownError "no parsable type")
	vs -> Right (last vs, [])
Camil Staps's avatar
Camil Staps committed
184
docBlockToDoc{|Type|} _ = abort "error in docBlockToDoc{|Type|}\n"
185

186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
docBlockToDoc{|PropertyBootstrapDoc|} (Left [s]) =
	let [opts:content] = split "\n" s in
	parseOpts opts >>= \(no_imports,ws) -> pure
		(
			{ bootstrap_content                 = MultiLine (trimMultiLine content)
			, bootstrap_without_default_imports = no_imports
			}
		, ws
		)
where
	parseOpts opts = case opts of
		"without default imports" ->
			Right (True,[])
		"" ->
			Right (False,[])
		_ ->
			Left (UnknownError "illegal header for property-bootstrap field")
docBlockToDoc{|PropertyBootstrapDoc|} _ = abort "error in docBlockToDoc{|PropertyBootstrapDoc|}\n"

205 206 207 208 209 210 211 212 213 214
docBlockToDoc{|Property|} (Left [s]) = let [signature:property] = split "\n" s in
		parseSignature signature >>= \(sig,ws1) ->
		parseProperty property >>= \(prop,ws2) ->
		Right (sig prop, ws1 ++ ws2)
where
	parseSignature :: !String -> Either ParseError (!String -> Property, ![ParseWarning])
	parseSignature s = case parse parser (fromString s) of
		Left es           -> Left (UnknownError "failed to parse property signature")
		Right (name,args) -> Right (ForAll name args, [])
	where
215
		parser :: Parser Char (!String, ![(String, Type)])
216 217 218 219 220 221 222 223 224 225 226 227 228 229
		parser = skipSpaces *>
			pMany (pSatisfy ((<>) ':')) >>= \name ->
			skipSpaces *> pToken ':' *>
			((skipSpaces *> pToken 'A' *> pToken '.' *>
			pMany
				(skipSpaces *>
				(liftA2 tuple
					(toString <$> pMany (pSatisfy (not o isSpace)))
					(pList [skipSpaces,pToken ':',pToken ':',skipSpaces] *> pTypeWithColonOrSemicolon)
				) <* skipSpaces)) <|> skipSpaces *> pure []) >>= \args ->
			pure (toString name, args)

		skipSpaces = pMany (pSatisfy isSpace) *> pYield undef
		pTypeWithColonOrSemicolon = (pMany (pSatisfy \c -> c <> ':' && c <> ';') <* pOneOf [':;'])
Mart Lubbers's avatar
Mart Lubbers committed
230
			>>= \t -> case parseType t of
231 232 233 234 235
				Nothing -> pError "type could not be parsed"
				Just t  -> pure t

	parseProperty :: ![String] -> Either ParseError (!String, ![ParseWarning])
	parseProperty ss = Right (trimMultiLine ss, [])
Camil Staps's avatar
Camil Staps committed
236
docBlockToDoc{|Property|} _ = abort "error in docBlockToDoc{|Property|}\n"
237 238

docBlockToDoc{|PropertyVarInstantiation|} (Left [s]) = case split "=" s of
Mart Lubbers's avatar
Mart Lubbers committed
239
	[var:type:[]] -> case parseType (fromString type) of
240 241 242
		Just t -> Right (PropertyVarInstantiation (trim var, t), [])
		Nothing -> Left (UnknownError "type could not be parsed")
	_ -> Left (UnknownError "property var instantiation could not be parsed")
Camil Staps's avatar
Camil Staps committed
243
docBlockToDoc{|PropertyVarInstantiation|} _ = abort "error in docBlockToDoc{|PropertyVarInstantiation|}\n"
244

245 246 247 248 249 250 251
docBlockToDoc{|PropertyTestGenerator|} (Left [s])
| startsWith "list: " sig = case parseType [c \\ c <-: sig & i <- [0..] | i > 4] of
	Just t  -> Right (PTG_List t imp, [])
	Nothing -> error
| otherwise = case parseType (fromString sig) of
	Just t  -> Right (PTG_Function t imp, [])
	Nothing -> error
252
where
253 254 255 256
	sig = trim sig`
	imp = trimMultiLine imp`
	[sig`:imp`] = split "\n" s
	error = Left (UnknownError "test generator could not be parsed")
Camil Staps's avatar
Camil Staps committed
257
docBlockToDoc{|PropertyTestGenerator|} _ = abort "error in docBlockToDoc{|PropertyTestGenerator|}\n"
258

259 260
derive docBlockToDoc ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
	ConstructorDoc, ClassDoc, TypeDoc
261

262 263 264 265 266 267 268 269 270 271
printDoc :: !d -> String | docToDocBlock{|*|} d
printDoc d = join "\n * "
	[ "/**"
	: (case desc of
		Nothing -> []
		Just d  -> [replaceSubString "\n" "\n * " d] ++ (if (isEmpty fields) [] [""])) ++
	  ["@" +++ f +++ " " +++ replaceSubString "\n" "\n *   " v \\ (f,v) <- fields]
	] +++
	"\n */"
where
Camil Staps's avatar
Camil Staps committed
272 273 274
	fields` = case docToDocBlock{|*|} False d of
		Right fs -> fs
		_        -> abort "error in printDoc\n"
275 276 277
	fields = filter ((<>) "description" o fst) fields`
	desc = lookup "description" fields`

Camil Staps's avatar
Camil Staps committed
278
generic docToDocBlock a :: !Bool !a -> Either [String] DocBlock
279
docToDocBlock{|String|} True s = Left [s]
Camil Staps's avatar
Camil Staps committed
280
docToDocBlock{|String|} _    _ = abort "error in docToDocBlock{|String|}\n"
281
docToDocBlock{|[]|} fx True xs = Left [x \\ Left xs` <- map (fx True) xs, x <- xs`]
Camil Staps's avatar
Camil Staps committed
282
docToDocBlock{|[]|} _  _    _  = abort "error in docToDocBlock{|[]|}\n"
283 284 285
docToDocBlock{|Maybe|} fx True mb = case mb of
	Nothing -> Left []
	Just x  -> fx True x
Camil Staps's avatar
Camil Staps committed
286 287 288 289 290 291 292 293 294 295 296
docToDocBlock{|Maybe|} _  _    _  = abort "error in docToDocBlock{|Maybe|}\n"

docToDocBlock{|PAIR|} fx fy False (PAIR x y) = case fx False x of
	Right xs -> case fy False y of
		Right ys -> Right (xs ++ ys)
		_        -> abort "error in docToDocBlock{|PAIR|}\n"
	_            -> abort "error in docToDocBlock{|PAIR|}\n"
docToDocBlock{|PAIR|} _  _  _      _         = abort "error in docToDocBlock{|PAIR|}\n"
docToDocBlock{|FIELD of d|} fx False (FIELD x) = case fx True x of
	Left xs -> Right [(name,x) \\ x <- xs]
	_       -> abort "error in docToDocBlock{|FIELD|}\n"
297 298 299 300 301 302
where
	name = {if (c=='_') '-' c \\ c <-: name`}
	name`
	| endsWith "ies" d.gfd_name = d.gfd_name % (0,size d.gfd_name-4) +++ "y"
	| endsWith "s" d.gfd_name   = d.gfd_name % (0,size d.gfd_name-2)
	| otherwise                 = d.gfd_name
Camil Staps's avatar
Camil Staps committed
303
docToDocBlock{|FIELD|} _ _ _ = abort "error in docToDocBlock{|FIELD|}\n"
304
docToDocBlock{|RECORD|} fx False (RECORD x) = fx False x
Camil Staps's avatar
Camil Staps committed
305
docToDocBlock{|RECORD|} _  _     _          = abort "error in docToDocBlock{|RECORD|}\n"
306 307 308 309 310 311 312 313

docToDocBlock{|ParamDoc|} True pd = case pd.ParamDoc.name of
	Nothing -> case pd.ParamDoc.description of
		Nothing -> Left []
		Just d -> Left [d]
	Just n -> case pd.ParamDoc.description of
		Nothing -> Left [n]
		Just d -> Left [n +++ ": " +++ d]
Camil Staps's avatar
Camil Staps committed
314
docToDocBlock{|ParamDoc|} _ _ = abort "error in docToDocBlock{|ParamDoc|}\n"
315
docToDocBlock{|MultiLineString|} True (MultiLine s) = Left [s]
Camil Staps's avatar
Camil Staps committed
316
docToDocBlock{|MultiLineString|} _    _             = abort "error in docToDocBlock{|MultiLineString|}\n"
317
docToDocBlock{|Type|} True t = Left [toString t]
Camil Staps's avatar
Camil Staps committed
318
docToDocBlock{|Type|} _    _ = abort "error in docToDocBlock{|Type|}\n"
319 320 321
docToDocBlock{|PropertyBootstrapDoc|} True bs_doc = Left $ [ if bs_doc.bootstrap_without_default_imports " without default imports" ""
	: map ((+++) "    ") $ split "\n" $ fromMultiLine bs_doc.bootstrap_content
	]
322 323
docToDocBlock{|Property|} True (ForAll name args impl) = Left
	[name +++ ": A." +++ join "; " [a +++ " :: " <+ t \\ (a,t) <- args] +++ ":\n" +++ impl]
Camil Staps's avatar
Camil Staps committed
324
docToDocBlock{|Property|} _ _ = abort "error in docToDocBlock{|Property|}\n"
325
docToDocBlock{|PropertyVarInstantiation|} True (PropertyVarInstantiation (a,t)) = Left [a +++ " = " <+ t]
Camil Staps's avatar
Camil Staps committed
326
docToDocBlock{|PropertyVarInstantiation|} _    _                                = abort "error in docToDocBlock{|PropertyVarInstantiation|}\n"
327 328 329 330 331
docToDocBlock{|PropertyTestGenerator|} True ptg = Left [t <+ "\n" +++ imp]
where
	(t,imp) = case ptg of
		PTG_Function t imp -> (t,imp)
		PTG_List t imp     -> (t,imp)
Camil Staps's avatar
Camil Staps committed
332
docToDocBlock{|PropertyTestGenerator|} _    _                              = abort "error in docToDocBlock{|PropertyTestGenerator|}\n"
333

334 335
derive docToDocBlock ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
	ClassDoc, ConstructorDoc, TypeDoc
336

337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
trimMultiLine :: ![String] -> String
trimMultiLine ss = join "\n" [s % (trimn, size s - 1) \\ s <- ss]
where
	trimn = minList [i \\ Just i <- map (firstNonSpace 0) ss]

	firstNonSpace :: !Int !String -> Maybe Int
	firstNonSpace i s
	| i >= size s   = Nothing
	| isSpace s.[i] = firstNonSpace (i+1) s
	| otherwise     = Just i

parseDocBlock :: !String -> Either ParseError (!DocBlock, ![ParseWarning])
parseDocBlock b = prepareString b >>= parsef
where
	parsef :: ![[Char]] -> Either ParseError (!DocBlock, ![ParseWarning])
	parsef [] = Right ([], [])
	parsef lines = case span (\l -> isEmpty l || hd l <> '@') lines of
		([],   [ln]) = parseFields [ln]
		([],   rest) = appSnd (\ws -> [NoDescription:ws]) <$> parseFields rest
		(desc, rest) = appFst (\d -> [("description", linesToString desc):d]) <$> parseFields rest

	parseFields :: ![[Char]] -> Either ParseError (!DocBlock, ![ParseWarning])
	parseFields []
		= Right ([], [])
	parseFields [['@':line]:rest]
		= parseFields rest` >>=
			\(d,ws) -> appSnd ((++) ws) <$> parseFs field desc d
	where
		(field, descline) = span (not o isSpace) line
		(restdesc, rest`) = span (\l -> isEmpty l || hd l <> '@') rest
		desc = flatten $ intersperse ['\n'] $ if (isEmpty descline) restdesc [tl descline:restdesc]

		parseFs :: ![Char] ![Char] !DocBlock -> Either ParseError (!DocBlock, ![ParseWarning])
		parseFs field val d = Right ([(toString field,toString (rtrim val)):d], [])
Camil Staps's avatar
Camil Staps committed
371 372
	parseFields _
		= abort "error in parseDocBlock\n"
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410

prepareString :: (String -> Either ParseError [[Char]])
prepareString = checkAsterisks o map trim o break '\n' o fromString
where
	checkAsterisks :: ![[Char]] -> Either ParseError [[Char]]
	checkAsterisks [['*':line]] = Right [safetl line]
	checkAsterisks [line] = Right [line]
	checkAsterisks lines
	| all (\l -> isEmpty l || hd l == '*') lines
		= Right $ map (safetl o dropWhile ((==) '*')) lines
		= Left $ MissingAsterisk $ toString $ hd $ filter (\l -> not (isEmpty l) && hd l <> '*') lines

	safetl :: ![a] -> [a]
	safetl []     = []
	safetl [_:xs] = xs

	break :: !a -> [a] -> [[a]] | == a
	break e = foldr f []
	where
		f x []     = if (x == e) []        [[x]]
		f x [y:ys] = if (x == e) [[]:y:ys] [[x:y]:ys]

linesToString :: ([[Char]] -> String)
linesToString = toString o flatten o intersperse ['\n']

instance toString ParseWarning
where
	toString (UnknownField f)   = "Doc warning: unknown field '" +++ f +++ "'"
	toString (IllegalField f)   = "Doc warning: illegal field '" +++ f +++ "'"
	toString NoDescription      = "Doc warning: missing description"
	toString UsedReturn         = "Doc warning: @return is deprecated, use @result"
	toString (UnparsableType t) = "Doc warning: could not parse type '" +++ t +++ "'"

instance toString ParseError
where
	toString (MissingAsterisk l) = "Doc error: missing leading asterisk in '" +++ l +++ "'"
	toString (MissingField f)    = "Doc error: required field '" +++ f +++ "' was missing"
	toString (UnknownError e)    = "Doc error: " +++ e
Camil Staps's avatar
Camil Staps committed
411
	toString InternalNoDataError = "Doc error: internal parsing error"
412 413 414 415 416 417 418 419 420 421 422

traceParseWarnings :: ![ParseWarning] !a -> a
traceParseWarnings []     x = x
traceParseWarnings [w:ws] x
| trace_tn w = traceParseWarnings ws x
| otherwise  = undef

traceParseError :: !ParseError !a -> a
traceParseError e x
| trace_tn e = x
| otherwise  = undef