I figure that how you treat the result of
GetUserThumbnailAsync relies heavily on the
ready bool. The value of the
content string is different depending on
ready. In some cases, a developer might completely ignore
ready is false and they want to do special loading logic.
I can see some general reasoning for
content coming first: one might just call
GetUserThumbnailAsync once and use the result, ignoring
ready. This way of using
GetUserThumbnailAsync is not common because it has some flaws:
- If it’s not
ready, then you don’t get an actual user thumbnail. If you don’t retry until
ready, then you’ll have blank or “loading” images lingering around your UI.
- Since this makes a web request, it needs to be
pcalled or you risk letting a larger part of the game error.
- If you do any retrying logic, you also have to have timeout logic in case the webpoint is down since trying forever would be bad.
I wouldn’t expect an API like this to put
content first since its use relies so heavily on
ready and since it can’t be called as a quick way to get the image without risking breaking larger parts of the game.
Both returns are important here, and these are not necessarily absolute reasons why
ready should be first. It doesn’t matter too much which one is first if it’s written out clearly.
I sort of agree.
I think that listing out all of the returns, their types, and their names in order is the standard for API documentation. Using the official Roblox API documentation when it lacks these things make it feel sub-par and incomplete.
Sometimes the documentation seems to be written more like an explanatory tutorial than a technical documentation. I don’t mind both in one, but I do mind when the technical documentation is missing. I see this as one such case, albeit a small one.
I hope I’m not being too harsh with my criticism here. Normally I overlook these things and just test it to clear my doubts. This post is a culmination of my slight frustration at missing or hard to find return parameter documentation from the past few months. I decided that I might as well do something about it if it bothers me.