Skip to content

GitLab

Verified Commit 37be2bff authored by Camil Staps's avatar Camil Staps
Browse files

Rewrite documentation parsing for easier extensibility

parent 85237f51
Hide whitespace changes
Inline Side-by-side
Showing with 330 additions and 444 deletions
CloogleDB.dcl
View file @ 37be2bff
......@@ -34,7 +34,7 @@ from Type import :: Type, :: TypeVar, :: TVAssignment, :: TypeDef,
from Cloogle import :: FunctionKind, :: SyntaxExample, :: CleanLangReportLocation
from Doc import :: Documentation
from Doc import :: FunctionDoc, :: TypeDoc, :: ClassDoc, :: ModuleDoc
/**
* A storage for function types, class definitions, type definitions, etc.
......@@ -58,24 +58,24 @@ from Doc import :: Documentation
, fe_generic_vars :: !Maybe [String] //* The names of the type variables of a generic function
// Using TypeVar causes import clashes in CloogleDBFactory
, fe_representation :: !Maybe String //* A string representation of the entry
, fe_documentation :: !Maybe Documentation //* Documentation on this entry
, fe_documentation :: !Maybe FunctionDoc //* Documentation on this entry
}
/**
* A TypeDef with meta-data
*/
:: TypeDefEntry
= { tde_typedef :: !TypeDef //* The TypeDef
, tde_doc :: !Maybe Documentation //* Documentation on the TypeDef (a TypeDoc)
= { tde_typedef :: !TypeDef //* The TypeDef
, tde_doc :: !Maybe TypeDoc //* Documentation on the TypeDef
}
/**
* Information about a Clean module
*/
:: ModuleEntry
= { me_is_core :: !Bool //* Whether this is a core module (e.g. the os* modules in ObjectIO and TCPIP)
, me_is_app :: !Bool //* Whether this module is not actually a library but an app
, me_documentation :: !Maybe Documentation //* Documentation on this module (a ModuleDoc)
= { me_is_core :: !Bool //* Whether this is a core module (e.g. the os* modules in ObjectIO and TCPIP)
, me_is_app :: !Bool //* Whether this module is not actually a library but an app
, me_documentation :: !Maybe ModuleDoc //* Documentation on this module
}
/**
......@@ -85,7 +85,7 @@ from Doc import :: Documentation
= { ce_vars :: ![String] //* The type variables of the class
// Using TypeVar causes import clashes in CloogleDBFactory
, ce_context :: !TypeContext //* A class context
, ce_documentation :: !Maybe Documentation //* Documentation on this class (a ClassDoc)
, ce_documentation :: !Maybe ClassDoc //* Documentation on this class
, ce_members :: ![(!Name, !FunctionEntry)] //* Class members: function name and type information
, ce_instances :: ![InstanceEntry] //* All instances of the class
, ce_derivations :: ![DeriveEntry] //* Derivations of generic meta-classes like iTask
......@@ -148,9 +148,9 @@ isBuiltin :: Location -> Bool
isCore :: Location CloogleDB -> Bool
isApp :: Location CloogleDB -> Bool
toTypeDefEntry :: TypeDef (Maybe Documentation) -> TypeDefEntry
toTypeDefEntry :: TypeDef (Maybe TypeDoc) -> TypeDefEntry
getTypeDef :: TypeDefEntry -> TypeDef
getTypeDefDoc :: TypeDefEntry -> Maybe Documentation
getTypeDefDoc :: TypeDefEntry -> Maybe TypeDoc
mergeTypeDefEntries :: TypeDefEntry TypeDefEntry -> TypeDefEntry
/**
......@@ -158,11 +158,11 @@ mergeTypeDefEntries :: TypeDefEntry TypeDefEntry -> TypeDefEntry
*
* @param The type variables of the class
* @param The class context
* @param The documentation (a ClassDoc)
* @param The documentation
* @param The names and types of the class members
* @result A Class record with those data
*/
toClass :: [String] TypeContext (Maybe Documentation) [(Name, FunctionEntry)] -> ClassEntry
toClass :: [String] TypeContext (Maybe ClassDoc) [(Name, FunctionEntry)] -> ClassEntry
functionCount :: CloogleDB -> Int
classCount :: CloogleDB -> Int
......
CloogleDB.icl
View file @ 37be2bff
......@@ -60,17 +60,19 @@ printersperse ia a bs = intercalate (print False a) (map (print ia) bs)
(--) a b = print False a ++ print False b
derive gEq Maybe, TypeRestriction, Location, Type, Priority, FunctionEntry,
TypeDef, TypeDefRhs, RecordField, Constructor, Kind, Documentation,
TypeRhsDoc, ClassMemberDoc, InstanceEntry, DeriveEntry,
CleanLangReportLocation
TypeDef, TypeDefRhs, RecordField, Constructor, Kind, FunctionDoc, ClassDoc,
TypeDoc, ModuleDoc, ClassMemberDoc, ConstructorDoc, InstanceEntry,
DeriveEntry, CleanLangReportLocation
derive JSONEncode TypeRestriction, Location, Type, CloogleDB, Priority,
FunctionEntry, TypeDef, TypeDefRhs, RecordField, Constructor, Kind,
ModuleEntry, Documentation, TypeRhsDoc, ClassMemberDoc, TypeDefEntry,
ClassEntry, InstanceEntry, DeriveEntry, SyntaxEntry
ModuleEntry, FunctionDoc, ClassDoc, TypeDoc, ModuleDoc, ClassMemberDoc,
ConstructorDoc, TypeDefEntry, ClassEntry, InstanceEntry, DeriveEntry,
SyntaxEntry
derive JSONDecode TypeRestriction, Location, Type, CloogleDB, Priority,
FunctionEntry, TypeDef, TypeDefRhs, RecordField, Constructor, Kind,
ModuleEntry, Documentation, TypeRhsDoc, ClassMemberDoc, TypeDefEntry,
ClassEntry, InstanceEntry, DeriveEntry, SyntaxEntry
ModuleEntry, FunctionDoc, ClassDoc, TypeDoc, ModuleDoc, ClassMemberDoc,
ConstructorDoc, TypeDefEntry, ClassEntry, InstanceEntry, DeriveEntry,
SyntaxEntry
instance zero CloogleDB
where
......@@ -164,13 +166,13 @@ isApp l db = case getModule l db of
Nothing -> False
Just b -> b.me_is_app
toTypeDefEntry :: TypeDef (Maybe Documentation) -> TypeDefEntry
toTypeDefEntry :: TypeDef (Maybe TypeDoc) -> TypeDefEntry
toTypeDefEntry td doc = {tde_typedef=td, tde_doc=doc}
getTypeDef :: TypeDefEntry -> TypeDef
getTypeDef {tde_typedef} = tde_typedef
getTypeDefDoc :: TypeDefEntry -> Maybe Documentation
getTypeDefDoc :: TypeDefEntry -> Maybe TypeDoc
getTypeDefDoc {tde_doc} = tde_doc
mergeTypeDefEntries :: TypeDefEntry TypeDefEntry -> TypeDefEntry
......@@ -179,7 +181,7 @@ mergeTypeDefEntries a=:{tde_typedef={td_rhs=TDRAbstract Nothing}} b = case b.tde
rhs -> {a & tde_typedef.td_rhs=TDRAbstract (Just rhs)}
mergeTypeDefEntries a b = b
toClass :: [String] TypeContext (Maybe Documentation) [(Name, FunctionEntry)] -> ClassEntry
toClass :: [String] TypeContext (Maybe ClassDoc) [(Name, FunctionEntry)] -> ClassEntry
toClass vs cc doc mems
= { ce_vars = vs
, ce_context = cc
......
CloogleDBFactory.icl
View file @ 37be2bff
......@@ -24,6 +24,8 @@ import System.Directory
import System.FilePath
from Text import class Text(concat,indexOf,replaceSubString), instance Text String
import GenDefault
import CleanPrettyPrint
from compile import :: DclCache{hash_table}, empty_cache
......@@ -63,15 +65,15 @@ from CloogleDB import :: Location(Location), filterLocations,
:: ModuleEntry{me_is_core,me_is_app,me_documentation},
:: FunctionEntry{fe_type,fe_kind,fe_generic_vars,fe_priority,fe_representation,fe_documentation},
instance zero FunctionEntry, instance zero ModuleEntry
from Doc import :: Documentation(FunctionDoc), :: ResultDoc, :: VarDoc,
:: ParamDoc, :: Description, :: TypeRhsDoc(ADTDoc,RecordDoc),
:: RecordFieldDoc, :: ClassMemberDoc,
:: ParseWarning(UsedReturn,IllegalField), :: ParseError(IllegalState),
parseFunctionDoc, parseConstructorDoc, parseADTypeDoc, parseRecordTypeDoc,
parseSynonymTypeDoc, parseAbstractTypeDoc, parseFieldDoc, parseClassDoc,
parseModuleDoc, traceParseError, traceParseWarnings, getTypeRhsDoc,
getTypeDoc, constructorToFunctionDoc, functionToClassMemberDoc,
addClassMemberDoc
from Doc import :: ModuleDoc, :: FunctionDoc{..}, :: ClassDoc, :: TypeDoc{..},
:: ConstructorDoc, :: ClassMemberDoc, :: Description,
:: ParseWarning(UsedReturn,IllegalField), :: ParseError,
generic docBlockToDoc, parseDoc, parseSingleLineDoc, :: DocBlock,
class docType(..), instance docType FunctionDoc,
class docConstructors(..), instance docConstructors TypeDoc,
class docFields(..), instance docFields TypeDoc,
traceParseError, traceParseWarnings,
constructorToFunctionDoc, functionToClassMemberDoc, addClassMemberDoc
:: TemporaryDB
= { temp_functions :: ![[(!'DB'.Location, !'DB'.FunctionEntry)]]
......@@ -285,18 +287,18 @@ where
pd_module :: ![ParsedDefinition] -> ModuleEntry
pd_module [PD_Documentation _ doc:_]
= { zero
& me_documentation = docParseResultToMaybe (const True) $ parseModuleDoc doc
& me_documentation = docParseResultToMaybe (const True) $ parseDoc doc
}
pd_module _ = zero
pd_rewriterules :: !Bool ![ParsedDefinition] SymbolTable -> [(LocationInModule, 'DB'.FunctionEntry)]
pd_rewriterules dcl defs st
= [( setLine dcl pos {zero & name=Just id.id_name}
, let doc = findDoc hideIsUsedReturn parseFunctionDoc id st in
, let doc = findDoc hideIsUsedReturn id st in
trace_type_warning id
{ zero
& fe_kind=Macro
, fe_type=(getTypeDoc =<< doc) <|> pdType pd
, fe_type=(docType =<< doc) <|> pdType pd
, fe_representation=Just $ priostring id pd +++ cpp pd
, fe_priority=findPrio id >>= 'T'.toMaybePriority
, fe_documentation=doc
......@@ -319,10 +321,6 @@ where
| id`.id_name == id.id_name = Just pd
findTypeSpec id [_:defs] = findTypeSpec id defs
needsTypeWarning :: (Maybe Documentation) -> Bool
needsTypeWarning Nothing = True
needsTypeWarning (Just (FunctionDoc _ _ _ _ t)) = isNothing t
trace_type_warning :: !Ident !FunctionEntry -> FunctionEntry
trace_type_warning id fe
| isJust (findTypeSpec id defs) = fe
......@@ -342,7 +340,7 @@ where
& fe_type=Just $ 'T'.toType gen_type
, fe_generic_vars=Just $ map 'T'.toTypeVar gen_vars
, fe_representation=Just $ cpp gen
, fe_documentation=findDoc hideIsUsedReturn parseFunctionDoc id st
, fe_documentation=findDoc hideIsUsedReturn id st
}
) \\ gen=:(PD_Generic {gen_ident=id=:{id_name},gen_pos,gen_type,gen_vars}) <- defs]
......@@ -353,7 +351,7 @@ where
& fe_type=Just $ 'T'.toType t
, fe_priority = 'T'.toMaybePriority p
, fe_representation = Just $ cpp ts
, fe_documentation = findDoc hideIsUsedReturn parseFunctionDoc id st
, fe_documentation = findDoc hideIsUsedReturn id st
}
) \\ ts=:(PD_TypeSpec pos id=:{id_name} p (Yes t) funspecs) <- defs]
......@@ -380,13 +378,14 @@ where
& fe_kind=if (isNothing $ lookup n macros) fe.fe_kind Macro
, fe_representation=lookup n macros <|> fe.fe_representation
, fe_documentation=if (isSingleFunction typespecs id)
(findDoc hideIsUsedReturn parseSingleFunctionDoc id st) fe.fe_documentation
((\d -> {FunctionDoc | d & vars=[]}) <$> findDoc hideIsUsedReturn id st)
fe.fe_documentation
}
in ( setLine dcl class_pos {zero & name=Just id_name}
, 'DB'.toClass
(map 'T'.toTypeVar class_args)
(flatten $ map 'T'.toTypeContext class_context)
(parseDoc typespecs id st)
(parseClassDoc typespecs id st)
[(f,updateRepresentation f et) \\ ({name=Just f}, et) <- typespecs]
)
\\ PD_Class {class_ident=id=:{id_name},class_pos,class_args,class_context} clsdefs <- defs
......@@ -396,17 +395,14 @@ where
// the class documentation as the function's documentation. This is the
// case for classes like `class zero a :: a`, which do not have a where
// clause and hence no other place for the function's documentation.
parseDoc :: [(LocationInModule, 'DB'.FunctionEntry)] Ident SymbolTable -> Maybe Documentation
parseDoc members id st
parseClassDoc :: [(LocationInModule, 'DB'.FunctionEntry)] Ident SymbolTable -> Maybe ClassDoc
parseClassDoc members id st
| isSingleFunction members id = flip addClassMemberDoc
(functionToClassMemberDoc <$> findDoc hideIsUsedReturn parseSingleFunctionDoc id st)
<$> findDoc hideFunctionOnClass parseClassDoc id st
(functionToClassMemberDoc <$> findDoc hideIsUsedReturn id st)
<$> findDoc hideFunctionOnClass id st
| otherwise = flip (foldl addClassMemberDoc)
[functionToClassMemberDoc <$> fe.fe_documentation \\ (_,fe) <- members]
<$> findDoc hideIsUsedReturn parseClassDoc id st
// Remove generic type variables from FunctionDoc; @var is for the class type variables
parseSingleFunctionDoc = fmap (appFst (\(FunctionDoc d ps vs r t) -> FunctionDoc d ps [] r t)) o parseFunctionDoc
<$> findDoc hideIsUsedReturn id st
isSingleFunction :: [(LocationInModule, 'DB'.FunctionEntry)] Ident -> Bool
isSingleFunction members id = length members == 1
......@@ -421,45 +417,34 @@ where
pd_types dcl defs st
= [let name = 'T'.td_name td in
( setLine dcl ptd.td_pos {zero & name=Just name}
, 'DB'.toTypeDefEntry td $ findRhsDoc ptd =<<
(case findDoc (const True) (parsef ptd.td_rhs) ptd.td_ident st of
Just d -> Just d
Nothing -> docParseResultToMaybe (const True) $ parsef ptd.td_rhs ""
)
, 'DB'.toTypeDefEntry td $ Just $ findRhsDoc ptd $ fromMaybe gDefault{|*|} $
findDoc (const True) ptd.td_ident st
) \\ PD_Type ptd <- defs, td <- ['T'.toTypeDef ptd]]
where
parsef :: RhsDefsOfType -> String -> Either ParseError (Documentation, [ParseWarning])
parsef (ConsList _) = parseADTypeDoc
parsef (ExtensibleConses _) = parseADTypeDoc
parsef (SelectorList _ _ _ _) = parseRecordTypeDoc
parsef (TypeSpec _) = parseSynonymTypeDoc
parsef (EmptyRhs _) = parseAbstractTypeDoc
parsef (AbstractTypeSpec _ _) = parseAbstractTypeDoc
parsef (MoreConses _ _ ) = parseADTypeDoc
parsef (NewTypeCons _ ) = const $ Left $ IllegalState "Unknown RhsDefsOfType: NewTypeCons"
parsef _ = const $ Left $ IllegalState "Unknown RhsDefsOfType"
findRhsDoc :: ParsedTypeDef Documentation -> Maybe Documentation
findRhsDoc {td_rhs=ConsList cs} doc = addConses cs doc
findRhsDoc {td_rhs=ExtensibleConses cs} doc = addConses cs doc
findRhsDoc {td_rhs=SelectorList _ _ _ fs} doc = addFields fs doc
findRhsDoc _ doc = Just doc
addFields :: [ParsedSelector] Documentation -> Maybe Documentation
addFields [] doc
= Just doc
addFields [{ps_doc=Yes d}:fs] doc
= addFields fs doc >>= docParseResultToMaybe (const True) o parseFieldDoc d
addFields [_:fs] doc
= addFields fs doc
addConses :: [ParsedConstructor] Documentation -> Maybe Documentation
findRhsDoc :: !ParsedTypeDef -> TypeDoc -> TypeDoc
findRhsDoc {td_rhs=ConsList cs} = addConses cs
findRhsDoc {td_rhs=ExtensibleConses cs} = addConses cs
findRhsDoc {td_rhs=SelectorList _ _ _ fs} = addFields fs
findRhsDoc _ = id
addFields :: ![ParsedSelector] !TypeDoc -> TypeDoc
addFields [] doc = doc
addFields [ps:fs] doc = {doc` & fields=Just [d:fromMaybe [] doc`.fields]}
where
doc` = addFields fs doc
d = case ps.ps_doc of
Yes d -> Just $ parseSingleLineDoc d
No -> Nothing
addConses :: ![ParsedConstructor] !TypeDoc -> TypeDoc
addConses [] doc
= Just doc
addConses [{pc_doc=Yes d}:cs] doc
= addConses cs doc >>= docParseResultToMaybe (const True) o parseConstructorDoc d
addConses [_:cs] doc
= addConses cs doc
= {doc & constructors=Just []}
addConses [pc:cs] doc = {doc` & constructors=Just [d:fromMaybe [] doc`.constructors]}
where
doc` = addConses cs doc
d = case pc.pc_doc of
Yes d -> docParseResultToMaybe (const True) (parseDoc d)
No -> Nothing
toLine :: Position -> 'DB'.LineNr
toLine (FunPos _ l _) = Just l
......@@ -486,8 +471,7 @@ where
= ((b1,b2,pm,ht,f),fs)
docParseResultToMaybe :: (ParseWarning -> Bool)
(Either ParseError (Documentation, [ParseWarning]))
-> Maybe Documentation
(Either ParseError (d, [ParseWarning])) -> Maybe d
docParseResultToMaybe showw (Left e)
= traceParseError e Nothing
docParseResultToMaybe showw (Right (doc,ws))
......@@ -496,11 +480,9 @@ where
hideIsUsedReturn :: ParseWarning -> Bool
hideIsUsedReturn w = not $ isUsedReturn w
findDoc :: (ParseWarning -> Bool)
(String -> Either ParseError (Documentation, [ParseWarning]))
Ident SymbolTable -> Maybe Documentation
findDoc showw parse {id_info} st = case sreadPtr id_info st of
{ste_doc=Yes doc} = docParseResultToMaybe showw $ parse doc
findDoc :: (ParseWarning -> Bool) Ident SymbolTable -> Maybe d | docBlockToDoc{|*|} d
findDoc showw {id_info} st = case sreadPtr id_info st of
{ste_doc=Yes doc} = docParseResultToMaybe showw $ parseDoc doc
_ = Nothing
isUsedReturn :: ParseWarning -> Bool
......@@ -527,9 +509,7 @@ where
print_prio Nothing = []
print_prio (Just p) = [" "] ++ print False p
cons_doc = case getTypeRhsDoc =<< 'DB'.getTypeDefDoc etd of
Just (ADTDoc conses) -> conses ++ repeat Nothing
_ -> repeat Nothing
cons_doc = fromMaybe [] (docConstructors =<< 'DB'.getTypeDefDoc etd) ++ repeat Nothing
record_functions :: 'DB'.TypeDefEntry -> [('DB'.Name, 'DB'.FunctionEntry)]
record_functions etd
......@@ -538,14 +518,12 @@ record_functions etd
& fe_kind=RecordField
, fe_type=Just t
, fe_representation=Just $ concat [".", f, " :: ":print False t]
, fe_documentation=(\d -> FunctionDoc (Just d) [] [] [] Nothing) <$> doc
, fe_documentation=(\d -> {FunctionDoc | gDefault{|*|} & description=Just d}) <$> doc
})
\\ (f,t) <- 'T'.recordsToFunctions ('DB'.getTypeDef etd)
& doc <- field_doc]
where
field_doc = case getTypeRhsDoc =<< 'DB'.getTypeDefDoc etd of
Just (RecordDoc fields) -> fields ++ repeat Nothing
_ -> repeat Nothing
field_doc = fromMaybe [] (docFields =<< 'DB'.getTypeDefDoc etd) ++ repeat Nothing
instance == (a,b,c,d) | == a & == b & == c & == d
where == (a,b,c,d) (p,q,r,s) = a == p && b == q && c == r && d == s
Doc.dcl
View file @ 37be2bff
......@@ -4,62 +4,114 @@ definition module Doc
* Parsing and storing Clean documentation
*/
import StdGeneric
from Data.Either import :: Either
from Data.Maybe import :: Maybe
from TypeDef import :: Type
/**
* Documentation on a Clean syntax element
*/
:: Documentation
= ModuleDoc (Maybe Description)
//* Documentation for a module
| FunctionDoc (Maybe Description) [ParamDoc] [VarDoc] [ResultDoc] (Maybe Type)
//* Documentation for a function, generic or macro
| ClassDoc (Maybe Description) [VarDoc] [Maybe ClassMemberDoc]
//* Documentation for a class
| TypeDoc (Maybe Description) [VarDoc] (Maybe TypeRhsDoc)
//* Documentation for a type definition
| ConstructorDoc (Maybe Description) [ParamDoc]
//* Documentation for a type constructor
from GenDefault import generic gDefault
class docDescription d :: d -> Maybe Description
class docParams d :: d -> [Description]
class docVars d :: d -> [Description]
class docResults d :: d -> [Description]
class docType d :: d -> Maybe Type
class docMembers d :: d -> [Maybe ClassMemberDoc]
class docFields d :: d -> Maybe [Maybe Description]
class docConstructors d :: d -> Maybe [Maybe ConstructorDoc]
class docRepresentation d :: d -> Maybe (Maybe Description)
/**
* Documentation for a Clean class member
* Documentation of a Clean module.
*/
:: ClassMemberDoc
= ClassMemberDoc (Maybe Description) [ParamDoc] [ResultDoc]
:: ModuleDoc =
{ description :: Maybe Description
}
instance docDescription ModuleDoc
derive gDefault ModuleDoc
/**
* Documentation for the right-hand side of a Clean type definition
* Documentation of a Clean function.
*/
:: TypeRhsDoc
= ADTDoc [Maybe Documentation]
//* For an algebraic data type. Only uses ConstructorDoc.
| RecordDoc [Maybe RecordFieldDoc]
//* For a record
| SynonymDoc (Maybe Description)
//* For a type synonym
:: FunctionDoc =
{ description :: Maybe Description
, params :: [Description] //* Descriptions of the parameters
, vars :: [Description] //* Descriptions of the type variables (for generics)
, results :: [Description] //* Descriptions of the result(s, for tuples)
, type :: Maybe Type //* The type (for macros)
}
instance docDescription FunctionDoc
instance docParams FunctionDoc
instance docVars FunctionDoc
instance docResults FunctionDoc
instance docType FunctionDoc
derive gDefault FunctionDoc
/**
* Documentation on the parameter of a function, generic, macro or class member
* Documentation of a Clean class member.
* For an explanation of the fields, see the documentation on {{`FunctionDoc`}}.
*/
:: ParamDoc :== Description
:: ClassMemberDoc =
{ description :: Maybe Description
, params :: [Description]
, results :: [Description]
, type :: Maybe Type
}
instance docDescription ClassMemberDoc
instance docParams ClassMemberDoc
instance docResults ClassMemberDoc
instance docType ClassMemberDoc
derive gDefault ClassMemberDoc
/**
* Documentation on a type variable for a type definition, class or generic
* Documentation of a Clean ADT constructor.
* For an explanation of the fields, see the documentation on {{`FunctionDoc`}}.
*/
:: VarDoc :== Description
:: ConstructorDoc =
{ description :: Maybe Description
, params :: [Description]
}
instance docDescription ConstructorDoc
instance docParams ConstructorDoc
derive gDefault ConstructorDoc
/**
* Documentation on a function result
* Documentation of a Clean class.
*/
:: ResultDoc :== Description
:: ClassDoc =
{ description :: Maybe Description
, vars :: [Description] //* The type variables
, members :: [Maybe ClassMemberDoc] //* Documentation on the members
}
instance docDescription ClassDoc
instance docVars ClassDoc
instance docMembers ClassDoc
derive gDefault ClassDoc
/**
* Documentation on a record field
* Documentation of a Clean type.
*/
:: RecordFieldDoc :== Description
:: TypeDoc =
{ description :: Maybe Description
, vars :: [Description] //* Type variables
, representation :: Maybe (Maybe Description) //* For synonym types
, fields :: Maybe [Maybe Description] //* For records
, constructors :: Maybe [Maybe ConstructorDoc] //* For ADTs
}
instance docDescription TypeDoc
instance docVars TypeDoc
instance docFields TypeDoc
instance docConstructors TypeDoc
instance docRepresentation TypeDoc
derive gDefault TypeDoc
/**
* Description of a Clean syntax element
......@@ -71,7 +123,8 @@ from TypeDef import :: Type
*/
:: ParseError
= MissingAsterisk String //* At least one line did not start with a *
| IllegalState String //* Incorrect usage of this module
| MissingField String //* A required field was missing
| UnknownError String //* Another error
/**
* Parse warning while parsing Clean documentation; the parser has made a
......@@ -84,147 +137,55 @@ from TypeDef import :: Type
| UsedReturn //* Used @return instead of @result
| UnparsableType String //* Could not parse a @type field as a type
/**
* Get the main description from a documentation
*/
getDocDescription :: Documentation -> Maybe Description
/**
* Get the documentation of the parameters of a documentation block
*
* @result All ParamDocs on the top level. If none can be given for the
* constructor of the parameter, the empty list is returned.
*/
getParamDocs :: Documentation -> [ParamDoc]
/**
* Get the documentation of the type variables of a documentation block
*
* @result All VarDocs on the top level. If none can be given for the
* constructor of the parameter, the empty list is returned.
*/
getVarDocs :: Documentation -> [VarDoc]
/**
* Get the documentation on the result of a FunctionDoc
*/
getResultDocs :: Documentation -> [ResultDoc]
/**
* Get the type of a FunctionDoc (should only be used for macros)
*
* @result The Type or Nothing
*/
getTypeDoc :: Documentation -> Maybe Type
/**
* Get the documentation on the right-hand side of a TypeDoc
*
* @result The documentation on the right-hand side, or Nothing if the
* parameter was not a TypeDoc or had no documentation on the RHS.
*/
getTypeRhsDoc :: Documentation -> Maybe TypeRhsDoc
/**
* Get the record fields of the TypeDoc of a record type
*
* @result The record fields or Nothing if the parameter was not of the right
* constructor.
*/
getFieldDoc :: Documentation -> Maybe [Maybe RecordFieldDoc]
/**
* Get the constructors of the TypeDoc of an algebraic data type