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
Docs: update doc for class-methods-use-this (fixes #8910) #9374
Docs: update doc for class-methods-use-this (fixes #8910) #9374
Conversation
LGTM |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM in general, but I think an example would be great. Feel free to wait for more opinions before making any changes, if you like: I won't insist on the example. Thanks for taking the time to improve our documentation; we really appreciate it!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the PR!
I think the resolution of #8910 (comment) was that the docs should convey the following information:
- If the user fixes this problem by changing an instance method to a static method, they also need to modify the places where the method is called.
- If the method is called by an external library, it might not be possible to fix the problem because the library might rely on the fact that the method is non-static.
In my opinion, the current description in this PR doesn't give enough detail for an inexperienced user to make an informed decision (since it's not clear when "sometimes" applies).
It seems like (1) is sort of mentioned already in the sentence above the Rule Details section, but I think that sentence could be improved:
- It's worded a bit strangely (it says "code calling the function ... changes"). It could be reworded to make it more explicit that the user is responsible for changing all the function callers.
- It's not placed very well. It comes after two code samples and right before another section, so it's not obvious that it's important when skimming the docs. In comparison, the slightly-misleading line that says "[an instance method] it can safely be made a static function" is right at the top of the page.
So my recommendations would be:
*. Reword the sentence above the Rule Details section to make the user's responsibility more explicit
*. (Possibly) move that sentence closer to the start of the page
*. Add a line to the exceptions section to describe when it might make sense to add exceptions (e.g. when using external libraries).
LGTM |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks!
[X] Documentation update
What changes did you make? (Give an overview)
Update the documentation that it is not 100% case that a method in a class that doesn't use
this
can be converted to a static method.This updates the text and links to mdn docs on classes and static methods.
Is there anything you'd like reviewers to focus on?
Not sure if it's beyond the scope to try and provide an example where you might not add a static