Documenting used containers of function return values

[2colours]

Relates to Raku/problem-solving#337

Hi,

for now, this is rather hypothetical because used assignments and containerization is a bit all over the place, so there is no need to work out something elaborate. I rather mean this as brainstorming and/or declaration of intents.

It would be nice to document if a certain function/method binds to containers, copies, or decontainerizes. Do you think this is a good idea, and if so, how do you think it could be added to the documentation (once clearly specified in the language)?

[coke]

This seems like a lot to add for everything; I assume there's a default behavior and we could document (hopefully a small number of) exceptions?

[2colours]

Yes. I think this question only truly matters for subs and methods that get their results from already existing values, so mostly methods of a Positional, Associative, etc.

[codesections]

Please correct me if I'm misunderstanding, but this is just about documenting binding/assignment/copying for return types, right? If I understand correctly, the current signatures already document binding/etc for parameters via is raw, is copy and such (or, if they don't, they are supposed to and the omission is a simple bug). Or is that not correct?

[2colours]

Alas, it's very-very included in the signatures. Yes, it might be enough if they were actually included. I don't know if they were supposed to but it would definitely make sense.

I think it would be good to get them in a more readable format than an e.g raw trait on the included signature - especially since the trait in itself doesn't guarantee if what you get in an is raw is indeed a container from the original data container. To say that you get the same container back that your data structure included is a bit more than that.