The generation of documentation with “Crystal docs” expands the alias definitions, which does not make the documentation easier to read, and also makes it less relevant, when the alias is a union of many types.
I have not found a solution to avoid this.
Is there one?
I have just created a minimal test app to illustrate my point.
Here is the code of the single source file.
alias DataType = Bool | Char | Int32 | Int64 | Float64 | String | Symbol | Time
getter value, index
def initialize(@value : DataType, @index : Int32)
alias Formatter = Proc(DataType, CellData, String) |
After running crystal docs, the HTML files contain:
For struct CellData:
def value : Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time
instead of expected:
def value : DataType
For formatter alias definition :
Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time -> String | Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time, Test::CellData -> String
Yeah, the type of #value is not declared, so the compiler deduces it. I suppose it could perhaps be more intelligent about it, but that’s just what you get. If you want an explicit type, then declare is explicitly.
That’s for 1. CellData#value.
The other examples (2.) about alias Formatter is a different story. That looks like an actual bug because what the doc generator produces here is plainly wrong. That’s not even valid syntax for the type grammar.