Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC See Also descriptions do not match for multiple functions/classes #24464

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

Closed
vitaliset opened this issue Sep 18, 2022 · 2 comments
Closed

Comments

@vitaliset
Copy link
Contributor

Describe the issue linked to the documentation

While working on a docstring-related pull request (#24259) I noticed that, sometimes, the See Also description for the same function/class does not match. For instance, the accuracy_score description was different depending on the class I looked at:

See Also
--------
accuracy_score : Function for calculating the accuracy score.

See Also
--------
accuracy_score : Compute the accuracy score. By default, the function will
return the fraction of correct predictions divided by the total number
of predictions.

I decided to investigate it further and see if it was occuring elsewhere (click here to check the gist where I regexed the raw files). Today, at commit 2f8b8e7f1, we have 56 functions/classes that have some sort of different descriptions at some See Also. From looking at them at first glance I have sorted the differences I get into 4 categorys:

  1. Those where the description is related to the current class/function;

    • For instance, inside the RegressorChain class, ClassifierChain is described as the "equivalent" version. That is a different description from the one we see inside MultiOutputClassifier, but inside the context of the RegressorChain class, it makes sense.
      See Also
      --------
      ClassifierChain : Equivalent for classification.
  2. Those related to extra "\n" on the text;

    SkewedChi2Sampler : Approximate feature map for "skewed chi-squared" kernel.

    SkewedChi2Sampler : Approximate feature map for
    "skewed chi-squared" kernel.

  3. Those that are different per se;

    • For instance, the accuracy_score descriptions we mentioned earlier have no obvious reason to be different.
  4. Those that are related to the docstring pattern.

Suggest a potential alternative/fix

I was planning on taking a closer look at the output table I get with the differences in the descriptions and coming up with the list of functions/classes that we should change to make it uniform across different occurrences of See Also.
Then, as this is a fairly beginner friendly issue, I would edit the issue description and give it a step-by-step (copying most part of what @thomasjpfan did in #21350) and let folks looking for a "good first issue" help. I would be happy to make sure the task bullets are up to date.

What do the maintainers think? Does it make sense? :)

PS: Of course, we will be forever vulnerable to this kind of issue if we don't create a test (maybe adapted from my gist). The problem here is that sometimes it just makes sense to have different descriptions... We can create an "ignore list" maybe, but we can discuss this later.

@vitaliset vitaliset added Documentation Needs Triage Issue requires triage labels Sep 18, 2022
@glemaitre
Copy link
Member

I don't know if we should define this issue as a priority. The difference with other documentation issues is that, in most cases, the description is correct.

@vitaliset
Copy link
Contributor Author

Thanks for the comment @glemaitre! I made a small pull request related to some doc typos I found here and will close this issue.

If someone does decide to solve this minor issue in the future, one can use the gist to find the mismatches and fix them quickly.

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

No branches or pull requests

2 participants