| There are type aliases as the ones described in the linked documentation - i.e. an autoloaded data type alias like:
type MyModule::MyType = SomeOtherType
|
For those it would be great if an adjacent comment is taken as documentation of the aliased type. Note that for some such declarations - it is not as much an alias as a type definition - for example:
type MyModule::MyType = Object[{ attributes => { name => String, birthdate => Timestamp}}]
|
There are also local type aliases in 4.x ruby functions. More complex functions use those to define aliases that are only in effect for a single function. Here is an example from the lookup() function:
local_types do |
type 'NameType = Variant[String, Array[String]]' |
type 'ValueType = Type' |
type 'DefaultValueType = Any' |
type 'MergeType = Variant[String[1], Hash[String, Scalar]]' |
type 'BlockType = Callable[NameType]' |
type "OptionsWithName = Struct[{\ |
name => NameType,\ |
value_type => Optional[ValueType],\ |
default_value => Optional[DefaultValueType],\ |
override => Optional[Hash[String,Any]],\ |
default_values_hash => Optional[Hash[String,Any]],\ |
merge => Optional[MergeType]\ |
}]" |
type "OptionsWithoutName = Struct[{\ |
value_type => Optional[ValueType],\ |
default_value => Optional[DefaultValueType],\ |
override => Optional[Hash[String,Any]],\ |
default_values_hash => Optional[Hash[String,Any]],\ |
merge => Optional[MergeType]\ |
}]" |
|
end |
|
dispatch :lookup_1 do |
scope_param |
param 'NameType', :name |
optional_param 'ValueType', :value_type |
optional_param 'MergeType', :merge |
end
|
Documenting those are a bit more difficult - should the signature of the function show the aliases only - for example NameType (then you have to guess, or read the general description what a NameType is (requires author of function doc to write that), should it use an expanded NameType instead of just the alias (more difficult to read), or should it present the list of local aliases? I think it would be great if we could show a list of aliases and then use those aliases in the multiple signatures.
It may be that 4.x local aliases is complex enough to warrant a separate ticket. |
