Skip to content
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.

Sign up for GitHub

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

Jump to bottom

proposal: doc: time: Clarification on Order of Operations and Normalization in AddDate() Documentation #71334

Closed
msmhrt opened this issue Jan 20, 2025 · 4 comments
Closed

proposal: doc: time: Clarification on Order of Operations and Normalization in AddDate() Documentation #71334

msmhrt opened this issue Jan 20, 2025 · 4 comments
Labels
Documentation Issues describing a change to documentation. Proposal
Milestone
Proposal

Comments

@msmhrt
Copy link

msmhrt commented Jan 20, 2025

Proposal Details

Hello Go Team,

I would like to propose an addition to the AddDate() function documentation to clarify the impact of the order of operations and normalization on the result.

Could you please include the following addition in the documentation for better clarity?

Additionally, it is important to note that while AddDate(1, 1, 1) applied to January 31, 2023, results in March 3, 2024, applying the same period increment in three separate steps—AddDate(0, 0, 1), AddDate(0, 1, 0), and AddDate(1, 0, 0)—results in March 1, 2024. Moreover, if the order of these three operations is changed, such as AddDate(0, 1, 0), AddDate(0, 0, 1), and AddDate(1, 0, 0), the result will be March 4, 2024. This illustrates that the order of operations can affect the outcome due to the normalization process.

I believe this addition will help users better understand the behavior of the AddDate() function.

Thank you for considering this suggestion.
@gopherbot gopherbot added this to the Proposal milestone Jan 20, 2025
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Jan 20, 2025
@gabyhelp
Copy link

Related Issues

(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

@seankhliao
Copy link
Member

I think that's unsuited for a doc comment, maybe a blog post somewhere.

@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Jan 20, 2025
@msmhrt
Copy link
Author

msmhrt commented Jan 20, 2025

Thank you for your response. I understand that detailed examples may not fit well in the main documentation. However, I believe a note in the doc comments or source comments could help users avoid unintended issues when refactoring multiple AddDate() calls into one, due to the normalization process. I appreciate your consideration of this suggestion.

@ianlancetaylor
Copy link
Member

This kind of thing belongs in an example. See https://pkg.go.dev/testing#hdr-Examples. Want to send a patch?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. Proposal
Projects
None yet
Milestone
Proposal
Development

No branches or pull requests
5 participants
@msmhrt @ianlancetaylor @gopherbot @seankhliao @gabyhelp