What are the return parameters of GetUserThumbnailAsync?

Bug Reports Documentation Issues
#1

The GetUserThumbnailAsync page doesn’t say the exact return parameters. It does give a few hints though:

I know that…

  • It returns multiple values
  • One of them is ready
  • One is the content string

I don’t know if this is ready, content or content, ready. Right now, the only way to know this is for me to test it. I should be able to use the API by looking at the documentation without testing.

1 Like
#2

I’d argue the order is implied by the order in which they are described in the paragraph - the content URL as first and the boolean as second. I agree the page (paragraph in particular) could be a little more explicit.

As for the “returns” header having no detail, I’ll fill in the summary but I can’t for technical reasons fill out the two types individually.

Will update this post when the page is updated.

4 Likes
#3

Implied documentation won’t give developers confidence when using the API. I figured the same but had a lot of doubt! I was only confident in my understanding of the API after testing it. This is made worse by the fact that ready, content makes more sense to me than content, ready.

A small sentence, “GetUserThumbnailAsync returns content, ready” would be sufficient to give me an understanding of the API with confidence that my understanding is correct.

#4

Confidence in API is good, I agree, but this is a little nitpicky. The name of the function is pretty straightforward in that the first return type will be what it says on the tin, and other returned data is icing on that cake. I’m not sure why bool followed by string makes would make more sense; if you could explain your thinking behind that it may help us account for it in the future.

#5

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 content if 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.

1 Like