:ToHSV suggested over .toHSV, but unclear how to use it

Bug Reports Documentation Issues
#1

Issue Description

If you’re familiar with using HSV in the past, the way to go was:

local color = Color3.new(1,1,1)
local h1, s1, v1 = Color3.toHSV(color)

So, if you’re going to converted to :ToHSV() like the Color3 documentation says, it would be assumed you would write the code as:

local color = Color3.new(1,1,1)
local h1, s1, v1 = Color3:ToHSV(color)

This is not the case however, you are meant to use it like so:

local color = Color3.new(1,1,1)
local h1, s1, v1 = color:ToHSV()

The documentation page has no example code, so for the longest time, I simply thought :ToHSV() was terribly broken. The page needs to be updated with example code, similar to how :ToHex() has some, to make it more clear how it is meant to be used!

image
image1400×1079 105 KB

In a very general sense, the entirety of the Color3 page should be updated to reflect more example code of how these various functions are to be used, given how each one has a little different style of usage!

Issue Area: Documentation Content
Page URL: Color3 | Roblox Creator Documentation

5 Likes
#2

The documentation does say that :ToHSV() is a method though; methods are always intended to be called on the object that you create with a constructor (which for a Color3 is .new(), fromRGB() etc.)
However, I do agree that they should include some code samples to make it clear for less experienced developers.

8 Likes
#3

Right so, :ToHSV() is a method, meaning that it requires a class object that should be called on a self object.

1 Like
#4

Being that it was formerly a function, and half of Color3 is still constructors, and half is methods though, it’s quite strange for the Color3 page to have nearly no examples of how anything works.

And with the old toHSV being a constructor, and now the newer one is a method, it certainly could use some added information about that swap.

#5

This is similar to Random:NextNumber() and Random.NextNumber.

But, yes, this is proper documentation. However, it does mention that it is the opposite of the fromHSV constructor, so that is potentially an issue.

#6

You can’t have methods without constructors?

It’s not a swap, it’s the opposite.

local colour = Color3.new(.5, 1, 0)

-- "deconstruct"
local h, s, v = colour:ToHSV()

-- construct
local colour2 = Color3.fromHSV(h, s, v)

print(colour == colour2) -- true

You can tell if something is a method based on whether it uses PascalCasing instead of dromedaryCasing. Since all Roblox methods use that for methods and dromedaryCasing for functions, as far as I’m aware atleast.

Also, all of these do the same thing, just for future reference

colour:ToHSV()

colour.ToHSV(colour)

colour2.ToHSV(colour)

-- this seems to be the actual "old" way of doing it, since Color3 doesn't seem to have a ToHSV
Color3.toHSV(colour)
-- if you were making your own class then it would be .ToHSV
1 Like
#7

The old code was Color3.toHSV(obj)
The new code is (obj):ToHSV()

That’s what I mean by, it was swapped. Any older code using HSV would be called on the Class [Color3] where as the newer code is called on the Color Object in question.

image
image732×129 12.7 KB

[h1 in this case would print out 0]

Particularly, the way this pop up says:

use Color3:ToHSV instead

adds some confusion. It makes it seem like you’re meant to call it on Color3, which is not the case.

Color3:ToHSV(color) 
-- this will error, however, the popup seems to imply this is how it is used

I am not discussing the constructor of Color3.fromHSV, at all in this post.

#8

Oh, I see.

So the issue isn’t here

But here

I don’t think this should be in #bug-reports:documentation-issues but rather in #bug-reports:studio-bugs, though I’m not completely sure.

.toHSV() isn’t a constructor, so I thought you meant .fromHSV().

#9

I’m confused on how exactly the documentation is unclear even without example code. The API is consistent with other APIs, ToHSV is under the methods tab and the documentation says it takes in no arguments since it lists no arguments.

If it were meant to be a static function it would be under a functions tab (like the math library and similar libraries).

2 Likes
#10

It’s a documentation issue, and adding more clarifying information [example code in particular] on the Color3 page, would help fix this issue.

#11

I would say that it’s a studio issue because this message is only shown in studio, and thus studio is the one showing the information incorrectly. Because the documentation is correct.

Though it could be that studio just grabs this as is from the documentation that we can’t see, then it would probably be a documentation issue.

Re-explaining every concept every time it’s used in the documentation is impossible and would make it harder to understand.

Imagine having this paragraph under every method. Even if it was just examples it would be a ton of repetition. Which would just make incorrect documentation more prominent, make it harder to keep up to date and make it harder to understand.

#12

Thanks for the report. I filed a ticket to our internal database.

2 Likes
#13

Hi all,
We’ve updated the Color3 docs page with some code samples that (hopefully) make it clearer on how to use the properties and methods.

Take care!

1 Like
#14