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

docs: Improve wording on stating that a method does not work in-place #346

Closed
zzril opened this issue Jun 5, 2023 · 3 comments · Fixed by #449
Closed

docs: Improve wording on stating that a method does not work in-place #346

zzril opened this issue Jun 5, 2023 · 3 comments · Fixed by #449
Assignees
@zzril
Labels
cleanup 🧹 Refactorings and other tasks that improve the code documentation 📖 Improvements or additions to documentation released Included in a release

Comments

@zzril
Copy link
Contributor

zzril commented Jun 5, 2023 •
edited by lars-reimann
Loading

Describe the bug

For methods that return a copy, rather than working in-place, I believe the standard wording in docstrings is:

"""
Returns a new table that/where/with [...].

[...]
"""

Currently, we have this sentence in most of our docstrings:

"""
[...]
This table is not modified.
[...]
"""

Might be unclear for some users what "this table" refers to.

This rule should also be added to the guidelines.

Certainly wrong is this:

    def tag_columns(self, target_name: str, feature_names: list[str] | None = None) -> TaggedTable:
        """
        Mark the columns of the table as target column or feature columns. The original table is not modified.

        This table is not modified.
        [...]
        """

Expected behavior

Agree on a standard wording to use everywhere.

Definitely fix the redundancy in tag_columns in src/safeds/data/tabular/containers/_table.py.
@zzril zzril added the documentation 📖 Improvements or additions to documentation label Jun 5, 2023
@github-project-automation github-project-automation bot moved this to Backlog in Library Jun 5, 2023
@zzril zzril added the cleanup 🧹 Refactorings and other tasks that improve the code label Jun 5, 2023
@PhilipGutberlet PhilipGutberlet moved this from Backlog to Todo in Library Jun 16, 2023
@daniaHu daniaHu moved this from Todo to Backlog in Library Jun 16, 2023
@daniaHu daniaHu moved this from Backlog to Todo in Library Jun 30, 2023
@zzril
Copy link
Contributor Author

zzril commented Jul 6, 2023

This rule should also be added to the guidelines.

This part of the issue will be resolved by #427.

@zzril zzril moved this from Todo to 🧱 Blocked in Library Jul 7, 2023
@zzril
Copy link
Contributor Author

zzril commented Jul 7, 2023

Blocked by #58 (which will add a bunch of new methods / docstrings in the TaggedTable class).

@zzril zzril moved this from 🧱 Blocked to Todo in Library Jul 9, 2023
@zzril zzril moved this from Todo to In Progress in Library Jul 13, 2023
@zzril zzril mentioned this issue Jul 13, 2023
Merged
@zzril zzril linked a pull request Jul 13, 2023 that will close this issue
docs: Improve wording on stating that a method does not work in-place #449
Merged
@zzril zzril moved this from In Progress to Ready for Review in Library Jul 13, 2023
@zzril zzril moved this from Ready for Review to Ready to Merge in Library Jul 13, 2023
zzril added a commit that referenced this issue Jul 13, 2023
@zzril @Marsmaennchen221 @megalinter-bot
docs: Improve wording on stating that a method does not work in-place (…
62e8fe9 
…#449)

Closes #346

### Summary of Changes

Updated the docstrings of methods in `src/safeds/data` to state that
copies are returned, with the original object left unmodified.

---------

Co-authored-by: Alexander <[email protected]>
Co-authored-by: megalinter-bot <[email protected]>
@github-project-automation github-project-automation bot moved this from Ready to Merge to ✔️ Done in Library Jul 13, 2023
@lars-reimann
Copy link
Member

🎉 This issue has been resolved in version 0.15.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

@lars-reimann lars-reimann added the released Included in a release label Jul 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@zzril zzril

Labels
cleanup 🧹 Refactorings and other tasks that improve the code documentation 📖 Improvements or additions to documentation released Included in a release
Projects
Library
Archived in project
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: Improve wording on stating that a method does not work in-place Safe-DS/Library
2 participants
@lars-reimann @zzril