astropy / astropy/pyvo

Miscellaneous doc string improvements

Open
#215 1 comment 0 reactions 0 assignees View on GitHub
bug documentation
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.