Parse parameter names

Clean/Doc.dcl

@@ -5,6 +5,7 @@ definition module Clean.Doc
  */
 
 import StdGeneric
+from StdOverloaded import class toString
 
 from Data.Either import :: Either
 from Data.GenDefault import generic gDefault
@@ -19,7 +20,7 @@ from Clean.Types import :: Type
 :: MultiLineString = MultiLine !String
 
 class docDescription            d :: !d -> Maybe Description
-class docParams                 d :: !d -> [Description]
+class docParams                 d :: !d -> [ParamDoc]
 class docVars                   d :: !d -> [Description]
 class docResults                d :: !d -> [Description]
 class docType                   d :: !d -> Maybe Type
@@ -55,7 +56,7 @@ derive gDefault ModuleDoc
  */
 :: FunctionDoc =
 	{ description        :: !Maybe Description
-	, params             :: ![Description] //* Descriptions of the parameters
+	, params             :: ![ParamDoc]    //* 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)
@@ -73,6 +74,17 @@ instance docThrows FunctionDoc
 instance docPropertyTestWith FunctionDoc
 instance docProperties FunctionDoc
 
+/**
+ * Documentation of a function parameter.
+ */
+:: ParamDoc =
+	{ name        :: !Maybe String      //* An optional name for the parameter
+	, description :: !Maybe Description //* An optional description
+	}
+
+instance toString ParamDoc
+instance docDescription ParamDoc
+
 /**
  * A property of a function.
  * Typically, the property can be tested with Gast.
@@ -105,7 +117,7 @@ derive gDefault FunctionDoc, Property, PropertyVarInstantiation, PropertyTestGen
  */
 :: ClassMemberDoc =
 	{ description :: !Maybe Description
-	, params      :: ![Description]
+	, params      :: ![ParamDoc]
 	, results     :: ![Description]
 	, type        :: !Maybe Type
 	, throws      :: ![Description]
@@ -124,7 +136,7 @@ derive gDefault ClassMemberDoc
  */
 :: ConstructorDoc =
 	{ description :: !Maybe Description
-	, params      :: ![Description]
+	, params      :: ![ParamDoc]
 	}
 
 instance docDescription ConstructorDoc

Clean/Doc.icl

@@ -14,6 +14,7 @@ import StdTuple
 import Control.Applicative
 import Control.Monad => qualified join
 import Data.Either
+import Data.Error
 from Data.Func import $
 import Data.Functor
 import Data.GenDefault
@@ -25,6 +26,8 @@ import qualified Text
 import Text.Language
 import Text.Parsers.Simple.ParserCombinators
 
+import Regex
+
 from Clean.Types import :: Type, :: TypeRestriction
 import qualified Clean.Types.Parse as T
 
@@ -47,6 +50,8 @@ instance docThrows           FunctionDoc where docThrows           d = d.Functio
 instance docProperties       FunctionDoc where docProperties       d = d.properties
 instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.FunctionDoc.property_test_with
 
+instance docDescription ParamDoc where docDescription d = d.ParamDoc.description
+
 instance docDescription ClassMemberDoc where docDescription d = d.ClassMemberDoc.description
 instance docParams      ClassMemberDoc where docParams      d = d.ClassMemberDoc.params
 instance docResults     ClassMemberDoc where docResults     d = d.ClassMemberDoc.results
@@ -66,9 +71,15 @@ instance docFields         TypeDoc where docFields         d = d.TypeDoc.fields
 instance docConstructors   TypeDoc where docConstructors   d = d.TypeDoc.constructors
 instance docRepresentation TypeDoc where docRepresentation d = d.TypeDoc.representation
 
+instance toString ParamDoc
+where
+	toString pd=:{name=Just n,description=Just d} = n +++ ": " +++ d
+	toString {ParamDoc | description=Just d} = d
+	toString _ = ""
+
 derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, ClassMemberDoc,
 	ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyVarInstantiation,
-	MultiLineString, PropertyTestGenerator
+	MultiLineString, PropertyTestGenerator, ParamDoc
 
 constructorToFunctionDoc :: !ConstructorDoc -> FunctionDoc
 constructorToFunctionDoc d =
@@ -134,6 +145,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
+		 }, [])
+	[]               -> Right ({name=Nothing, description=Just s}, [])
+where
+	rgx = regex ['^(\\w+):\\s*(.+)$']
+
 docBlockToDoc{|Type|} (Left []) = Left InternalNoDataError
 docBlockToDoc{|Type|} (Left ss) = case [v \\ Just v <- map ('T'.parseType o fromString) ss] of
 	[] -> Left (UnknownError "no parsable type")

CleanRegex @ 0d974e7e

-Subproject commit 2c5edcee074fff52cd6e5ab188b506a40f362a6c
+Subproject commit 0d974e7efb1677f8450d78eae13596dfd5aad807

Cloogle/DB.icl

@@ -64,13 +64,13 @@ instance < AnnotationKey where < a b = (a =?= b) === LT
 derive JSONEncode ClassDoc, ClassEntry, ClassMemberDoc, CloogleEntry,
 	Constructor, ConstructorDoc, DeriveEntry, FunctionDoc, FunctionEntry,
 	InstanceEntry, Location, ModuleDoc, ModuleEntry, Priority, RecordField,
-	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc,
+	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc, ParamDoc,
 	TypeRestriction, ABCInstructionEntry, Property, PropertyVarInstantiation,
 	MultiLineString, NGramIndex, PropertyTestGenerator, Regex, GroupId
 derive JSONDecode ClassDoc, ClassEntry, ClassMemberDoc, CloogleEntry,
 	Constructor, ConstructorDoc, DeriveEntry, FunctionDoc, FunctionEntry,
 	InstanceEntry, Location, ModuleDoc, ModuleEntry, Priority, RecordField,
-	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc,
+	SyntaxEntry, Type, TypeDef, TypeDefEntry, TypeDefRhs, TypeDoc, ParamDoc,
 	TypeRestriction, ABCInstructionEntry, Property, PropertyVarInstantiation,
 	MultiLineString, NGramIndex, PropertyTestGenerator, Regex, GroupId
 

Cloogle/Search.icl

@@ -134,7 +134,7 @@ makeResult orgsearchtype allsyns usedsyns (entry, annots) db
 			_           -> Nothing
 		, generic_derivations = sortBy ((<) `on` fst) <$>
 			map (\{value=DeriveEntry de} -> (de.de_type_representation, map locResult de.de_locations)) <$> derivs
-		, param_doc = docParams <$> fe.fe_documentation
+		, param_doc = map toString <$> docParams <$> fe.fe_documentation
 		, generic_var_doc = docVars <$> fe.fe_documentation
 		, result_doc = docResults <$> fe.fe_documentation
 		, type_doc = concat <$> print False <$> (docType =<< fe.fe_documentation)

README.md

@@ -102,12 +102,12 @@ do), `CloogleDBFactory` can derive the type.</sup>
 
 | Field             | Description
 |-------------------|-------------
-| `@param`          | Parameters of a function(-like)
-| `@representation` | The representation of a synonym type
-| `@result`         | The result of a function
-| `@return`         | A deprecated synonym of `@result`
-| `@type`           | The type of a macro (without name and `::`)
-| `@var`            | Type variables of types, classes and generics
+| `@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`.
+| `@type`           | The type of a macro (without name and `::`).
+| `@var`            | Type variables of types, classes and generics.
 
 ### Property documentation