Given functions with multiple clauses it is often required to declare a function head for documentation purposes:
def size(map_with_size)
def size(%{size: size}) do
size
end
The documentation currently infers the function argument types and no doubt any additional type annotations could improve that, but the doc function argument labelling requirement will remain.
Given multiple function heads with different type signatures, it would be something to consider that we don’t have to declare all 3 things orthogonally:
- the function with its arguments and guards
- the function type annotations (repeating the guard constraints?)
- the function head documentation signature labelling the arguments
I know it’s early days but are there any thoughts on some kind of convergance of annotations with documentation, (aka doctypes) being considered?
I certainly don’t want more distractions on function heads but I also like the type annotation to be immediately above the function body it actually applies to like @attr in Phoenix components and not grouped up away from the function definition.
I would be concerned of the disconnect between type annotation and the function body it applies to. It’s not hard to conceive of example where it would be quite a bit of mental analysis to determine which type annotation applies to what function variant.
I was also thinking that what is done for Phoneix components is an existing example of documenting types and expectations.
Components specify type constraints and documentation for a single assigns argument which are compile time checked and produce useful documentation.
Could something similar to this style of approach be extended to all function arguments merging the document action and the constraints?
Could we specify constraints on maps, keyword lists and fields of structs. Given component @attr and @slot annotations are already constraining an assigns map is this a useful use case to model?
