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 docstrings and readme #39

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

apexDev37
Copy link

@apexDev37 apexDev37 commented May 29, 2024

Description

This PR introduces minor patches to improve the docs by updating docstrings and README.md files to improve user experience.

Patches made:

  • Enhance clarity of docstrings for learners.
  • Fix typos and grammar errors.

Testing

N/A: This branch does not introduce functional code. No tests are to be run.

Additional

Codespell:

  • The following Python package, codespell was used to find spelling errors in the repo and fix them interactively.
# NB: Warnings raised on `package-lock.json` can be safely ignored.
(trivia) ➜  trivia git:(docs-minor-patch) codespell .
./backend/README.md:9: virual ==> virtual, visual, viral
./frontend/README.md:123: cateogry ==> category
./frontend/package-lock.json:955: Ue ==> Use, Due
./frontend/package-lock.json:8175: bU ==> by, be, but, bug, bun, bud, buy, bum
./frontend/package-lock.json:10677: vise ==> vice
./frontend/package-lock.json:13627: vEw ==> view, vow, vex
./frontend/package-lock.json:15185: trough ==> through
./frontend/package-lock.json:15187: trough ==> through
./frontend/package-lock.json:15361: trough ==> through
./frontend/package-lock.json:15683: vise ==> vice
./frontend/package-lock.json:15685: vise ==> vice
./frontend/package-lock.json:17403: Ue ==> Use, Due
./frontend/package-lock.json:23245: bU ==> by, be, but, bug, bun, bud, buy, bum
./frontend/package-lock.json:25244: vise ==> vice
./frontend/package-lock.json:27596: vEw ==> view, vow, vex
./frontend/package-lock.json:28879: trough ==> through
./frontend/package-lock.json:28881: trough ==> through
./frontend/package-lock.json:29004: trough ==> through
./frontend/package-lock.json:29288: vise ==> vice
./frontend/package-lock.json:29290: vise ==> vice

Recommendation:
IMO, the following alternative TODO docstring should be used over the current one to provide students with clearer instructions.

This requires a Review or Input.

# Recommended.
"""@TODO: For each endpoint, write at least two tests:

- A success test to ensure it functions correctly with valid input.
- An error test to verify it handles invalid input as expected.
"""
# Current.
"""
@TODO:
Write at least one test for each endpoint for successful operation and for expected errors.
"""

Merge checklist:
Check off if complete or not applicable:

  • Version bumped
  • Changelog record added
  • Documentation updated (not only docstrings)
  • Fixup commits are squashed away
  • Unit tests added/updated
  • Manual testing instructions provided
  • Noted any: Concerns, dependencies, migration issues, deadlines, tickets

Patch docstrings with the following:
- Fix grammar and typo errors.
- Annotate `TODO` for consistency throughout project.

[Note]
TODOs in project adhere to the following style: `@TODO:`
Patch `README` files by fixing typos to improve user experience.

[Note]
Py package `codespell` was used to find and fix typos in the repo.

[Commands]
➜ codespell .
➜ codespell -i 3 -w

[Docs]
See: https://github.com/codespell-project/codespell
@apexDev37 apexDev37 requested a review from a team as a code owner May 29, 2024 21:29
@apexDev37 apexDev37 requested review from SudKul and removed request for a team May 29, 2024 21:29
@apexDev37
Copy link
Author

⚡Fun fact: Former Udacity Alumni (Full-Stack Web Developer Nanodegree), glad to give back!

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

Successfully merging this pull request may close these issues.

1 participant