Merge branch 'documentation-on-instances' into 'master'

Add support for documentation on instances

See merge request !270

doc/DOCUMENTATION.md

@@ -67,7 +67,7 @@ information.
 | Constructor  | ![][y]      |          |           |         |        |                   |           |
 | Function     | ![][y]      | ![][y]   | ![][y]    |         |        |                   | ![][y]    | ![][y]
 | Generic      | ![][y]      | ![][y]   | ![][y]    |         | ![][y] |                   |           |
-| Instance     |             |          |           |         |        |                   |           |
+| Instance     | ![][y]      |          |           |         |        |                   |           |
 | Macro        | ![][y]      | ![][y]   | ![][y]    | ![][y]<sup>2</sup> | |               |           |
 | Module       | ![][y]      |          |           |         |        |                   |           |
 | Record field | ![][y]      |          |           |         |        |                   |           |

src/libraries/OS-Independent/Clean/Doc.dcl

@@ -35,6 +35,7 @@ class docPropertyBootstrap      d :: !d -> Maybe String
 class docPropertyTestWith       d :: !d -> [PropertyVarInstantiation]
 class docPropertyTestGenerators d :: !d -> [PropertyTestGenerator]
 class docProperties             d :: !d -> [Property]
+class docPreconditions          d :: !d -> [String]
 
 /**
  * Documentation of a Clean module.
@@ -76,8 +77,26 @@ instance docVars FunctionDoc
 instance docResults FunctionDoc
 instance docType FunctionDoc
 instance docThrows FunctionDoc
-instance docPropertyTestWith FunctionDoc
 instance docProperties FunctionDoc
+instance docPropertyTestWith FunctionDoc
+instance docPreconditions FunctionDoc
+
+/**
+ * Documentation of a class instance.
+ */
+:: InstanceDoc =
+	{ description        :: !Maybe Description
+	, complexity         :: !Maybe String  //* E.g. "O(n log n)"
+	, properties         :: ![Property] //* Properties of this instance
+	, property_test_with :: ![PropertyVarInstantiation] //* With which types to test the properties
+	, preconditions      :: ![String]   //* Preconditions for the properties
+	}
+
+instance docDescription InstanceDoc
+instance docComplexity InstanceDoc
+instance docProperties InstanceDoc
+instance docPropertyTestWith InstanceDoc
+instance docPreconditions InstanceDoc
 
 /**
  * Documentation of a function parameter.
@@ -123,7 +142,7 @@ instance docDescription ParamDoc
 	= PTG_Function !Type !String
 	| PTG_List !Type !String
 
-derive gDefault FunctionDoc, Property, PropertyVarInstantiation, PropertyTestGenerator
+derive gDefault FunctionDoc, InstanceDoc, Property, PropertyVarInstantiation, PropertyTestGenerator
 
 /**
  * Documentation of a Clean class member.
@@ -264,8 +283,8 @@ generic docBlockToDoc d :: !(Either [String] DocBlock) -> Either ParseError (!d,
 
 derive docBlockToDoc UNIT, PAIR, EITHER, CONS, OBJECT, FIELD of {gfd_name}, RECORD
 derive docBlockToDoc String, [], Maybe, Type
-derive docBlockToDoc ModuleDoc, FunctionDoc, ClassMemberDoc, ClassDoc,
-	ConstructorDoc, TypeDoc
+derive docBlockToDoc ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
+	ClassDoc, ConstructorDoc, TypeDoc
 
 /**
  * Print a documentation block as a string. The magic happens in
@@ -279,8 +298,8 @@ printDoc :: !d -> String | docToDocBlock{|*|} d
  */
 generic docToDocBlock d :: !Bool !d -> Either [String] DocBlock
 
-derive docToDocBlock ModuleDoc, FunctionDoc, ClassMemberDoc, ClassDoc,
-	ConstructorDoc, TypeDoc
+derive docToDocBlock ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
+	ClassDoc, ConstructorDoc, TypeDoc
 
 /**
  * Trace a list of ParseWarnings like StdDebug might do it

src/libraries/OS-Independent/Clean/Doc.icl

@@ -48,8 +48,15 @@ instance docVars             FunctionDoc where docVars             d = d.Functio
 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
-instance docProperties       FunctionDoc where docProperties       d = d.properties
+instance docProperties       FunctionDoc where docProperties       d = d.FunctionDoc.properties
 instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.FunctionDoc.property_test_with
+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
 
 instance docDescription ParamDoc where docDescription d = d.ParamDoc.description
 
@@ -79,9 +86,9 @@ where
 	toString {ParamDoc | description=Just d} = d
 	toString _ = ""
 
-derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, ClassMemberDoc,
-	ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyVarInstantiation,
-	MultiLineString, PropertyTestGenerator, ParamDoc
+derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, InstanceDoc,
+	ClassMemberDoc, ConstructorDoc, ClassDoc, TypeDoc, Property,
+	PropertyVarInstantiation, MultiLineString, PropertyTestGenerator, ParamDoc
 
 constructorToFunctionDoc :: !ConstructorDoc -> FunctionDoc
 constructorToFunctionDoc d =
@@ -230,8 +237,8 @@ where
 	error = Left (UnknownError "test generator could not be parsed")
 docBlockToDoc{|PropertyTestGenerator|} _ = abort "error in docBlockToDoc{|PropertyTestGenerator|}\n"
 
-derive docBlockToDoc ModuleDoc, FunctionDoc, ClassMemberDoc, ConstructorDoc,
-	ClassDoc, TypeDoc
+derive docBlockToDoc ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
+	ConstructorDoc, ClassDoc, TypeDoc
 
 printDoc :: !d -> String | docToDocBlock{|*|} d
 printDoc d = join "\n * "
@@ -302,8 +309,8 @@ where
 		PTG_List t imp     -> (t,imp)
 docToDocBlock{|PropertyTestGenerator|} _    _                              = abort "error in docToDocBlock{|PropertyTestGenerator|}\n"
 
-derive docToDocBlock ModuleDoc, FunctionDoc, ClassMemberDoc, ClassDoc,
-	ConstructorDoc, TypeDoc
+derive docToDocBlock ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
+	ClassDoc, ConstructorDoc, TypeDoc
 
 trimMultiLine :: ![String] -> String
 trimMultiLine ss = join "\n" [s % (trimn, size s - 1) \\ s <- ss]

src/libraries/OS-Independent/Clean/Parse/Comments.icl

@@ -55,7 +55,7 @@ from syntax import
 	:: ParsedDefinition(..),
 	:: ParsedExpr,
 	:: ParsedImport,
-	:: ParsedInstance{pi_pos},
+	:: ParsedInstance{pi_ident,pi_pos},
 	:: ParsedInstanceAndMembers{pim_pi},
 	:: ParsedModule,
 	:: ParsedSelector{ps_field_pos,ps_field_ident},
@@ -346,6 +346,8 @@ where
 	commentIndex pd = case pd of
 		PD_Function pos id is_infix args rhs kind -> Just (CI "PD_Function" pos id.id_name)
 		PD_TypeSpec pos id prio type specials -> Just (CI "PD_TypeSpec" pos id.id_name)
+		PD_Instance {pim_pi=pi} -> Just (CI "PD_Instance" pi.pi_pos pi.pi_ident.id_name)
+		PD_Instances [{pim_pi=pi}:_] -> Just (CI "PD_Instances" pi.pi_pos pi.pi_ident.id_name)
 		PD_Class cd pds -> Just (CI "PD_Class" cd.class_pos cd.class_ident.id_name)
 		PD_Type ptd -> Just (CI "PD_Type" ptd.td_pos ptd.td_ident.id_name)
 		PD_Generic gd -> Just (CI "PD_Generic" gd.gen_pos gd.gen_ident.id_name)