Comments for describing flow parameters

[brig]

I want to revive this pull request. I think it might be useful :)

let's decide on the format of comments for describing parameters?
We can then implement comment parsers in the plugin, and the IDEA plugin will use them.

propose the following format:

##  
#  <FLOW_DESCRIPTION>  
#  in:  
#    myParam: <PARAM_TYPE>, mandatory|optional, <PARAM_DESCRIPTION>  
#  out:  
#    myParam: <PARAM_TYPE>, mandatory|optional, <PARAM_DESCRIPTION>  
## 

Where:

<FLOW_DESCRIPTION>: A description of the flow, optional parameter.

<PARAM_TYPE>:

• Basic types: string | int | number | boolean | object | any
• Arrays: string[] | int[] | number[] | boolean[] | object[] | any[]
  int === number, just an alias

<PARAM_DESCRIPTION>: A description of the parameter, optional parameter.

If you need to describe an object:

##  
#  in:  
#    objectParam: object, mandatory|optional, <PARAM_DESCRIPTION>  
#    objectParam.key1: <PARAM_TYPE>, mandatory|optional, <PARAM_DESCRIPTION>  
#    objectParam.key2: <PARAM_TYPE>, mandatory|optional, <PARAM_DESCRIPTION>  
##  

We can describe parameters with a JSON schema or by specifying name:, type:, required:, etc., but that makes each parameter take more than one line, so the description ends up longer than the flow itself. :)