os: ambiguous documentation of type FileMode

[mib-kd743naq]

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

N/A

Does this issue reproduce with the latest release?

Yes ( latest document online )

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

N/A

What did you do?

Read documentation of the FileMode bitfields

What did you expect to see?

Either

• ...The values of the lowest 9 bits should be considered part of the public API...
  OR
• ...The values of any of the 32 bits already defined in the const listing below should be considered part of the public API...

What did you see instead?

• ...The values of these bits should be considered part of the public API...

The documentation as currently written is clearly open to interpretation. Further discussion: https://botbot.me/freenode/go-nuts/2018-05-16/?msg=100120706&page=5

[ianlancetaylor]

I guess the text could be read to be ambiguous. When the comment says "these bits should be considered part of the public API" it refers to all the bits, not just the nine least-significant bits.

[mib-kd743naq]

I guess the text could be read to be ambiguous ... it refers to all the bits, not just the nine least-significant bits.

Note that @GinjaNinja32 read the documentation exactly the opposite way, so a fix is clearly in order ;)

[bcmills]

In context, I would interpret it to mean:
“The numeric values of the single-bit FileMode constants should be considered part of the public API […].”

[vikramcse]

@bcmills @ianlancetaylor

The defined file mode bits are the most significant bits of the FileMode. The nine least-significant bits are the standard Unix rwxrwxrwx permissions. The numeric values of the single-bit FileMode constants should be considered part of the public API and may be used in wire protocols or disk representations: they must not be changed, although new bits might be added.

Should I raise CL with above comment?

[ianlancetaylor]

I think we should separate the non-single-bit constants into a separate const block and adjust the comment as needed to make clear which ones can not change.

In truth changing any of the constant values would break Go 1 compatibility but it does make sense to clarify that the single-bit flags especially can't be changed.

[Windsooon]

How about

The nine least-significant bits are the standard Unix rwxrwxrwx permissions (permissions bits). Permissions bits should be considered part of the public API and may be used in wire protocols or disk representations which must not be changed, although new bits might be added.

[mib-kd743naq]

@bcmills @ianlancetaylor this ticket is over a year old. Could we bump it a bit? Thanks!

[ianlancetaylor]

Want to send in a pull request?

[Windsooon]

I can send a PR is we are ok with my suggestion.

[ianlancetaylor]

Sounds reasonable, thanks.