theupdateframework / theupdateframework/python-tuf
Improve docstrings on exceptions
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 304
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 17
Description
Current behavior:
Currently, in tuf/api/metadata.py we are using multiple ways to document our custom TUF exceptions.
There are two main ways of how we handle exceptions:
- there are places where we define an exception with the full module name:
https://github.com/theupdateframework/python-tuf/blob/0f1fc6e33cbc4d4c6b502b9f8c64b119d1a4ad2f/tuf/api/metadata.py#L185 - and in other cases, we document only the name of the exception: https://github.com/theupdateframework/python-tuf/blob/0f1fc6e33cbc4d4c6b502b9f8c64b119d1a4ad2f/tuf/api/metadata.py#L346
Expected behavior:
Decide how we want to document our exceptions and stick to that.
Document how we should write docstrings about exceptions somewhere.
I didn't find any mentions about the exception docstrings in the Google Python guidelines
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in tuf/api/metadata.py at the exception docstrings around the referenced lines 185 and 346, and compare the two documented styles. Decide on one consistent exception-docstring convention, update the affected docstrings, and document the convention somewhere in the project; done means the styles are consistent and the guidance is available.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100