New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

os: ambiguous documentation of type FileMode #25422

Open
mib-kd743naq opened this Issue May 16, 2018 · 5 comments

Comments

Projects
None yet
5 participants
@mib-kd743naq

mib-kd743naq commented May 16, 2018

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 ianlancetaylor changed the title from Ambiguous documentation of type FileMode to os: ambiguous documentation of type FileMode May 16, 2018

@ianlancetaylor ianlancetaylor added this to the Unplanned milestone May 16, 2018

@ianlancetaylor

This comment has been minimized.

Contributor

ianlancetaylor commented May 16, 2018

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

This comment has been minimized.

mib-kd743naq commented May 16, 2018

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

This comment has been minimized.

Member

bcmills commented May 16, 2018

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

This comment has been minimized.

vikramcse commented Aug 4, 2018

@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

This comment has been minimized.

Contributor

ianlancetaylor commented Aug 5, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment