Add optional single type description tag

[fvacek]

No description provided.

[Cynerd]

I am not sure about this. I have two lines of thinking...

Don't we have method documentation for this? This is less about type hinting and more about hinting on usage. I accept that both are pretty, but still, they have different aims. On the other hand, I am not against providing meaningful hints as part of the type hint, so I am not outright against it. I am just thinking if we don't have two different ways of doing the same thing at that point. The original use case of the KEY aliases through the type hints was to allow easier attribute entering (foo=1 bar=2 instead of i{1:1,2:2}) and more descriptive printing (especially for bitfields). That also leads me into an issue when this hint will be visible or used for displaying the type. It will always be better to display the type directly so should it be label of the result and if so should it be used for the parameter? The type hints are semi-readable. They are expected to be more used by validation software than read and that is why I am thinking when such a label would be used as I do not expect reader to just loot at the mess of the type hints to see this label.

The second issue I have is the way it is formulated. It is not clear when it can be used and when not. By having it to be the same syntax like KEY it kind of limits the usage. You can't just use it anywhere except the root type, which is all right (although implied it is not fully defined so). But should it apply only to simple types? Such as b:something. Or doesn't it make sense for lists as well? [s]:nodes. In such case shouldn't we allow it for all root types? i{i:x,i:y}:point. But that kind of breaks when used with "one of": like this s:name|n or like this s|n:name? The second one looks weird. So the first one? If the first one what about dual number like this one is:ttl|ds:ttl. If we tie back the map and imap design it should thus rather be is|ds:ttl instead?

It might be a good idea, but it needs work, I think. I am not sure if it just fits the current type hints design.

[fvacek]

Don't we have method documentation for this? This is less about type hinting and more about hinting on usage. I accept that both are pretty, but still, they have different aims. On the other hand, I am not against providing meaningful hints as part of the type hint, so I am not outright against it. I am just thinking if we don't have two different ways of doing the same thing at that point. The original use case of the KEY aliases through the type hints was to allow easier attribute entering (foo=1 bar=2 instead of i{1:1,2:2}) and more descriptive printing (especially for bitfields). That also leads me into an issue when this hint will be visible or used for displaying the type. It will always be better to display the type directly so should it be label of the result and if so should it be used for the parameter? The type hints are semi-readable. They are expected to be more used by validation software than read and that is why I am thinking when such a label would be used as I do not expect reader to just loot at the mess of the type hints to see this label.

My motivation is that I can do the same by issuing [s:api_key], but I didn't want to create single item tuple to achieve this. In other words, we have descriptive type description for complex types, but nothing for single type. My proposal is to extend something, what we have for complex types to single ones.

Documentation can be used for this, but this way can dir return more information.

[fvacek]

The second issue I have is the way it is formulated. It is not clear when it can be used and when not. By having it to be the same syntax like KEY it kind of limits the usage. You can't just use it anywhere except the root type, which is all right (although implied it is not fully defined so). But should it apply only to simple types? Such as b:something. Or doesn't it make sense for lists as well? [s]:nodes. In such case shouldn't we allow it for all root types? i{i:x,i:y}:point. But that kind of breaks when used with "one of": like this s:name|n or like this s|n:name? The second one looks weird. So the first one? If the first one what about dual number like this one is:ttl|ds:ttl. If we tie back the map and imap design it should thus rather be is|ds:ttl instead?

I think that we can have even s:name|n:not_found.

We will loose option to give name to whole one of, but do we need this? If yes, we can leave it as not possible.