Verified Commit dfdf84c9 authored by Camil Staps's avatar Camil Staps 🚀

Allow empty description for named properties; add @complexity

parent a4efa1db
......@@ -20,6 +20,7 @@ from Clean.Types import :: Type
:: MultiLineString = MultiLine !String
class docDescription d :: !d -> Maybe Description
class docComplexity d :: !d -> Maybe String
class docParams d :: !d -> [ParamDoc]
class docVars d :: !d -> [Description]
class docResults d :: !d -> [Description]
......@@ -56,6 +57,7 @@ derive gDefault ModuleDoc
*/
:: FunctionDoc =
{ description :: !Maybe Description
, complexity :: !Maybe String //* E.g. "O(n log n)"
, params :: ![ParamDoc] //* Descriptions of the parameters
, vars :: ![Description] //* Descriptions of the type variables (for generics)
, results :: ![Description] //* Descriptions of the result(s, for tuples)
......@@ -66,6 +68,7 @@ derive gDefault ModuleDoc
}
instance docDescription FunctionDoc
instance docComplexity FunctionDoc
instance docParams FunctionDoc
instance docVars FunctionDoc
instance docResults FunctionDoc
......@@ -117,6 +120,7 @@ derive gDefault FunctionDoc, Property, PropertyVarInstantiation, PropertyTestGen
*/
:: ClassMemberDoc =
{ description :: !Maybe Description
, complexity :: !Maybe String
, params :: ![ParamDoc]
, results :: ![Description]
, type :: !Maybe Type
......@@ -124,6 +128,7 @@ derive gDefault FunctionDoc, Property, PropertyVarInstantiation, PropertyTestGen
}
instance docDescription ClassMemberDoc
instance docComplexity ClassMemberDoc
instance docParams ClassMemberDoc
instance docResults ClassMemberDoc
instance docType ClassMemberDoc
......
......@@ -42,6 +42,7 @@ instance docPropertyTestWith ModuleDoc where docPropertyTestWith d = d.ModuleD
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
......@@ -53,6 +54,7 @@ instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.Functio
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
......@@ -93,6 +95,7 @@ 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
......@@ -146,13 +149,15 @@ docBlockToDoc{|OBJECT|} fx doc = appFst OBJECT <$> fx doc
docBlockToDoc{|MultiLineString|} (Left [s]) = Right (MultiLine $ trimMultiLine $ split "\n" s, [])
docBlockToDoc{|ParamDoc|} (Left [s]) = case match rgx (fromString s) of
[(_,_,groups):_] -> Right
({ name = toString <$> lookup (NotNamed 0) groups
, description = toString <$> lookup (NotNamed 1) groups
}, [])
[(_,_,groups):_] -> Right (
{ name = toString <$> lookup (NotNamed 0) groups
, description = case lookup (NotNamed 1) groups of
Just cs=:[_:_] -> Just (toString cs)
_ -> Nothing
}, [])
[] -> Right ({name=Nothing, description=Just s}, [])
where
rgx = regex ['^(\\w+):\\s*(.+)$']
rgx = regex ['^(\\w+):\\s*(.*)$']
docBlockToDoc{|Type|} (Left []) = Left InternalNoDataError
docBlockToDoc{|Type|} (Left ss) = case [v \\ Just v <- map ('T'.parseType o fromString) ss] of
......
......@@ -82,18 +82,18 @@ The tables below describe which fields and documentation types can be used for
different syntax elements, and what they should document. An extension, to
document test properties, is discussed below.
| | Description | `@param` | `@result` | `@type` | `@var` | `@representation` | `@throws`
|--------------|-------------|----------|-----------|---------|--------|-------------------|----------
| Class | ![][y] | ![][y]<sup>1</sup> | ![][y]<sup>1</sup> | | ![][y] | ![][y]
| Class member | ![][y] | ![][y] | ![][y] | | | | ![][y]
| Constructor | ![][y] | | | | | |
| Function | ![][y] | ![][y] | ![][y] | | | |
| Generic | ![][y] | ![][y] | ![][y] | | ![][y] | |
| Instance | | | | | | |
| Macro | ![][y] | ![][y] | ![][y] | ![][y]<sup>2</sup> | | |
| Module | ![][y] | | | | | |
| Record field | ![][y] | | | | | |
| Type | ![][y] | | | | ![][y] | ![][y], for type synonyms |
| | Description | `@param` | `@result` | `@type` | `@var` | `@representation` | `@throws` | `@complexity`
|--------------|-------------|----------|-----------|---------|--------|-------------------|-----------|--------------
| Class | ![][y] | ![][y]<sup>1</sup> | ![][y]<sup>1</sup> | | ![][y] | |
| Class member | ![][y] | ![][y] | ![][y] | | | | ![][y] | ![][y]
| Constructor | ![][y] | | | | | | |
| Function | ![][y] | ![][y] | ![][y] | | | | ![][y] | ![][y]
| Generic | ![][y] | ![][y] | ![][y] | | ![][y] | | |
| Instance | | | | | | | |
| Macro | ![][y] | ![][y] | ![][y] | ![][y]<sup>2</sup> | | | |
| Module | ![][y] | | | | | | |
| Record field | ![][y] | | | | | | |
| Type | ![][y] | | | | ![][y] | ![][y], for type synonyms | |
<sup>1: only for shorthand classes like `class zero a :: a`, where there is no
other place for the documentation of the class member.</sup>
......@@ -102,10 +102,12 @@ do), `CloogleDBFactory` can derive the type.</sup>
| Field | Description
|-------------------|-------------
| `@complexity` | E.g. "O(n log n)".
| `@param` | Parameters of a function(-like). Name a parameter using `@param name: description`.
| `@representation` | The representation of a synonym type.
| `@result` | The result of a function.
| `@return` | A deprecated synonym of `@result`.
| `@throws` | iTasks exceptions that can be thrown.
| `@type` | The type of a macro (without name and `::`).
| `@var` | Type variables of types, classes and generics.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment