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.

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

Merged

Conversation

VictorHom
Copy link
Member

[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

@eslintbot
Copy link

LGTM

Copy link
Member

@platinumazure platinumazure left a 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!

Copy link
Member

@not-an-aardvark not-an-aardvark left a 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:

  1. 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.
  2. 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).

@eslintbot
Copy link

LGTM

@not-an-aardvark not-an-aardvark added documentation Relates to ESLint's documentation accepted There is consensus among the team that this change meets the criteria for inclusion labels Oct 2, 2017
Copy link
Member

@not-an-aardvark not-an-aardvark left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

@not-an-aardvark not-an-aardvark merged commit 74dfc87 into eslint:master Oct 6, 2017
@eslint-deprecated eslint-deprecated bot locked and limited conversation to collaborators Apr 5, 2018
@eslint-deprecated eslint-deprecated bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Apr 5, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
accepted There is consensus among the team that this change meets the criteria for inclusion archived due to age This issue has been archived; please open a new issue for any further discussion documentation Relates to ESLint's documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants