Crystal docs: how to prevent alias expansion?

Help & Support
1

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?

2

That shouldn’t be happening. Where do you get an alias resolved?

Example in stdlib docs: Colorize::Object(T) - Crystal 1.6.2 (Color is an alias, it’s not expanded).

3

I have just created a minimal test app to illustrate my point.
Here is the code of the single source file.

module Test
  alias DataType = Bool | Char | Int32 | Int64 | Float64 | String | Symbol | Time

  struct CellData
    getter value, index

    def initialize(@value : DataType, @index : Int32)
    end
  end

  alias Formatter = Proc(DataType, CellData, String) |
                    Proc(DataType, String)
end

After running crystal docs, the HTML files contain:

  1. For struct CellData:
def value : Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time

instead of expected:

def value : DataType
  1. For formatter alias definition :
Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time -> String | Bool | Char | Float64 | Int32 | Int64 | String | Symbol | Time, Test::CellData -> String

instead of:

DataType -> String | DataType, CellData, -> String

As you can see, both aliases DataType and Formatter are expanded.

4

Ah, that’s a feature I introduced where the type of getters is deduced if not specified, for docs. You can fix this by specifying the type of the getter to be the alias.

1 Like
5

Forgot to say: it’ll be tricky to fix this.

6

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.

7

It works with

getter value : DataType

Thanks.

I also noticed that replacing

getter value

by

def value
  @value
end

also expands DataType.

8

I didn’t notice the generated expanded code for Formatter was incorrect !
Should I declare an issue for that ?

9

Right, that’s the general rule that was added to the docs generator. I’m wondering if if we should revert that rule.

1 Like