Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Cloogle
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Service Desk
Milestones
Merge Requests
0
Merge Requests
0
Operations
Operations
Incidents
Analytics
Analytics
Repository
Value Stream
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Cloogle
Cloogle
Commits
37be2bff
Verified
Commit
37be2bff
authored
Dec 14, 2017
by
Camil Staps
🚀
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Rewrite documentation parsing for easier extensibility
parent
85237f51
Changes
6
Hide whitespace changes
Inline
Side-by-side
Showing
6 changed files
with
330 additions
and
444 deletions
+330
-444
CloogleDB.dcl
CloogleDB.dcl
+12
-12
CloogleDB.icl
CloogleDB.icl
+12
-10
CloogleDBFactory.icl
CloogleDBFactory.icl
+56
-78
Doc.dcl
Doc.dcl
+109
-148
Doc.icl
Doc.icl
+129
-184
Search.icl
Search.icl
+12
-12
No files found.
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
,
Type
RhsDoc
,
ClassMemberDoc
,
InstanceEntry
,
Deriv
eEntry
,
CleanLangReportLocation
TypeDef
,
TypeDefRhs
,
RecordField
,
Constructor
,
Kind
,
FunctionDoc
,
ClassDoc
,
Type
Doc
,
ModuleDoc
,
ClassMemberDoc
,
ConstructorDoc
,
Instanc
eEntry
,
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
,
parseRecordType
Doc
,
parseSynonymTypeDoc
,
parseAbstractTypeDoc
,
parseFieldDoc
,
parseClass
Doc
,
parseModuleDoc
,
traceParseError
,
traceParseWarnings
,
getTypeRhs
Doc
,
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
Function
Doc
,
class
docConstructors
(..),
instance
docConstructors
Type
Doc
,
class
docFields
(..),
instance
docFields
Type
Doc
,
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
)
$
parse
Module
Doc
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
)
(
parse
Class
Doc
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.
parse
Doc
::
[(
LocationInModule
,
'
DB
'.
FunctionEntry
)]
Ident
SymbolTable
->
Maybe
Documentation
parseDoc
members
id
st
parse
ClassDoc
::
[(
LocationInModule
,
'
DB
'.
FunctionEntry
)]
Ident
SymbolTable
->
Maybe
ClassDoc
parse
Class
Doc
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 o
n a function result
* Documentation o
f 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 o
n a record field
* Documentation o
f 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
*
* @result The constructors or Nothing if the parameter was not of the right
* constructor.
*/
getConstructorDoc
::
Documentation
->
Maybe
[
Maybe
Documentation
]