Miscellaneous doc string improvements
- Dominant language
- Python
- Stars
- 88
- Forks
- 64
- Avg merge
- 38m
- Merged PRs (30d)
- 1
Description
While implementing a few queries I stumbled across some corrections/improvements that could be made to the in-code documentation. No doubt there are plenty of others, and a thorough review wouldn't be a bad idea, but here is a start:
https://github.com/astropy/pyvo/blob/96443beb9e623bd2ff5a2cbb143001188dfbef37/pyvo/registry/regtap.py#L330
- Replace the reference to a nonexistent 'database' search with a reference to TAP.
- Says that `self.search()` is equivalent to `self.to_service().search()`, but `to_service()` doesn't exist. It should be just `service()`, which is a little inconsistent with RegistryResults where `table()` has been deprecated in favor of `to_table()`.
https://github.com/astropy/pyvo/blob/96443beb9e623bd2ff5a2cbb143001188dfbef37/pyvo/dal/query.py#L426
- Typo in deprecation warning.
https://github.com/astropy/pyvo/blob/96443beb9e623bd2ff5a2cbb143001188dfbef37/pyvo/dal/sia.py#L188
- Has 2 different descriptions for `size` argument, neither of which are very clear about what you can/should supply. (This function doc is repeated multiple places in sia.py.)
- Documents the `intersect` argument which is not required for SIA services and probably isn't well-supported. The docs should at least have that caveat.
https://github.com/astropy/pyvo/blob/96443beb9e623bd2ff5a2cbb143001188dfbef37/pyvo/dal/query.py#L291
- votable arg is listed as a string but is really a astropy.io.votable.tree.VOTableFile
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the docstrings and warning at the referenced locations in pyvo/registry/regtap.py, pyvo/dal/query.py, and pyvo/dal/sia.py. Correct the named references, typo, argument descriptions, caveat, and VOTableFile type so the in-code documentation matches the APIs and supported behavior. Done means each listed discrepancy is addressed without expanding into an unspecified full review.
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
- 52/100