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