Crystal docs: how to prevent alias expansion?

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?

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).

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)

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

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.

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

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

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.

It works with

getter value : DataType


I also noticed that replacing

getter value


def value

also expands DataType.

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

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