occurences of 'may not' to be more descriptive for issue #83584

[jessehorne]

I did a grep -rl "may not" library/ and went through each instance of may not and made my best guess to what each meant and changed them to be more descriptive. For example, "Humans may not fly." would become "Humans can not fly." or "Humans may not breathe 100% carbon dioxide" to "Humans should not breathe 100% carbon dioxide".

Again, I made my best guess. Please let me know if there are any that are not accurate. I chose not to modify any may or may not's because those are pretty self-explanatory.

Fixes #83584

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @kennytm (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[egilburg]

Perhaps follow IEFT RFC 2119 for guidance on using these terms? For example, use "should" for best practice advice, and use "must" for things like compiler guarantees or places where failure to do so will cause undefined behavior.

[jessehorne]

Perhaps follow IEFT RFC 2119 for guidance on using these terms? For example, use "should" for best practice advice, and use "must" for things like compiler guarantees or places where failure to do so will cause undefined behavior.

I agree with RFC 2119 for the most part but I wish it had defined "WILL"/"WILL NOT". Given our use-case, I don't feel like following it exactly would make much sense. For example, if a function is designed to return 1, do you say in the documentation that "this function MUST return '1'", or "this function SHOULD return '1'"? For declaring intent of the implementation, I think "WILL" makes more sense. "MUST" sounds more like you're giving another party information. "WILL" sounds like you're saying "This was designed for that!".

That being said, I didn't use "WILL" at all in this. I mostly just changed from "may not" to either "should not" or "might not" depending on the scenario. While I agree that a standard is helpful when using these terms in documentation, oftentimes it seemed that the use of "may not" in these cases were pretty clear IF you read the previous documentation to gain context. I see the value of this if nothing else to just make it that much clear and potentially save time.

[bors]

☔ The latest upstream changes (presumably #84008) made this pull request unmergeable. Please resolve the merge conflicts.

[JohnCSimon]

Ping from triage:
@jessehorne - can you please address the merge conflict?

@rustbot label: -S-waiting-on-review +S-waiting-on-author

[crlf0710]

@jessehorne I'm gonna close this due to inactivity. Feel free to reopen or create a new pr when you've got time to work on this again. Thanks!