strconv: Atoi documentation is slightly misleading

[awulkan]

What version of Go are you using (go version)?

$ go version 1.11.4

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

Irrelevant.

go env Output

$ go env

What did you do?

Look at the documentation here: https://golang.org/src/strconv/atoi.go?s=5013:5045#L192

What did you expect to see?

An explanation of strconv.Atoi that matched what it actually did.

What did you see instead?

An explanation that is only half true.

Atoi returns the result of ParseInt(s, 10, 0) converted to type int.

It appears that Atoi doesn't just return the value of ParseInt(s, 10, 0), it only calls ParseInt as a last alternative, the "slow path". Without checking the code I was under the belief that I could just replace Atoi with ParseInt and it would basically run the exact same code.

It appears that the documentation was correct up until this commit:
46aa9f5#diff-cbef0f4cdbfb7c355433bb342a5ef463

[josharian]

Genuine question: Why do you care?

[awulkan]

@josharian What's the point of having documentation if it's outdated? I don't see why it would be a problem to update it to reflect the current state of the code, or make it more "high level" so it doesn't end up getting outdated like this the next time it's changed.

[ALTree]

Please note that the point of the documentation is not to describe the way the function is implemented under the hood. The only purpose of the documentation associated with the function signature is to explain what the function does (in the sense: what will it return when you call it).

So, in this case, the following sentence

Atoi returns the result of ParseInt(s, 10, 0)

is not telling you that the Atoi code, literally, is return Parseint(...). It's just a concise way to explain what the function does. Basically, the doc it's telling you that Atoi is a shortcut for ParseInt calls on base 10 number strings.

IMO the documentation appears "outdated" to you because you're reading it too literally.

[ALTree]

Anyway, here's a proposal for a slightly more high-level doc:

func Atoi(s string) (int, error)

Atoi interprets the string s as a base 10 integer, and returns its value as an int type. It is functionally equivalent to a call to ParseInt(s, 10, 0). See ParseInt doc for a description of the returned error's semantic.

[awulkan]

I'm sorry if I was a bit unclear. I never meant that I expected the comment to explain in great details what it did under the hood. I was just a bit surprised when the comment didn't match up with the reality. Afaik the "short path" is a lot faster than the ParseInt path, so there's a performance difference between Atoi and simply running ParseInt directly.

[bitfield]

Your honour, my client's statement never claimed that Atoi necessarily calls ParseInt, merely that it returns the same result as ParseInt. I move for a dismissal on the grounds that the defendant has no case to answer.

[awulkan]

@bitfield I didn't come here to argue. If no one else thinks it's an issue then fine, simply don't change it and close this issue.

The documentation does claim that it returns the result of ParseInt, not the same result as ParseInt though. Which led me to believe that it simply called ParseInt (as it once did).

Right now the documentation does try to explain what happens under the hood, but the documentation got outdated when the commit I linked to was introduced.

[gopherbot]

Change https://golang.org/cl/155924 mentions this issue: strconv: make docs for Itoa and Atoi slightly higher level

[bitfield]

@bitfield I didn't come here to argue. If no one else thinks it's an issue then fine, simply don't change it and close this issue.

It's been fixed!