18935, "stonea", "Improve doc \ error message on how to print out name of a type", "2022-01-07T18:38:01Z"
I just spent about 20 minutes trying to figure out how to print out type names in Chapel.
My first attempt of just doing:
writeln(myType.type)
but that didn’t work. Or at least not in the way I wanted it to (it does print an error message that reveals the type).
So I was thinking maybe there was a function type.name() or something like that so I open the language doc and look at the “Types” and “Reflections” section under “Standard Modules” but that didn’t reveal anything.
Finally it occurred to me (hey why don’t I try casting it to a string) and sure enough it worked! Looking back at the doc I see now that we do cover this in the “Language Specification” section for types (here: Types — Chapel Documentation 1.25). Specifically in this line:
It is possible to cast a type to a param string. This allows a type to be printed out.
Although in this case I don’t think I would have found that particular sentence as I was ctrl+f’ing around pages looking for “name” (not “cast” or “print” or anything like that).
One suggestion (from @dlonecker) would be specialize writeln to handle this case (or print an error message). Although we wouldn't be able to handle this for multi-argument cases like:
writeln("x's value is: ", x, " and its type is ", x.type) because of the issue noted here here: write and writeln does not support type argument · Issue #16917 · chapel-lang/chapel · GitHub (we don’t support tuples nor varargs that mix types and values).
Some specific changes I could make to the doc to improve this are:
- Add the word “name” to the sentence describing the cast so if I ctrl+f for that I’m likely to find it.
- Duplicate the information (about casting a type to a string tp print its name) in the “Standard Modules > Types” section.
- Have the “Standard Modules > Types” section link to the “Language Specification > Types” section in some easily noticeable way. That is have some banner at the top of the page telling me that if I don’t find the information I’m looking here maybe I should check out this other page.
Regarding the third bullet I have a more general issue about that here: (Add a section (or banner) like "see also" or "related topics" to top or bottom of doc pages · Issue #18934 · chapel-lang/chapel · GitHub), so maybe hold off on that one for this issue.