cytomining / cytomining/CytoTable

Enhance documentation and typing for interface composability

Open
#26 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
21
Forks
6
Avg merge
2d 3h
Merged PRs (30d)
6

Description

> "Later on, while documenting the interface (both public and private) I think it'd be helpful for a reader to know how the methods within the library are composed or could be composed. You could do this by calling out methods that rely on the current method or vice versa in the docs (e.g., "called by X(), used as input to Y()"), to at least demonstrate one example of how they could be composed. If you wanted to take this idea further, you could define named types (https://docs.python.org/3/library/typing.html#type-aliases) that are returned or taken as arguments to the methods. For example, `to_parquet()` takes several arguments whose types are `Union[List[str], Tuple[str, ...]]`; if you were to instead distinguish each argument as a type of the thing you expect it to take, you could simply read the signatures of `to_parquet()` and other methods in the library to see how you'd chain them together.

> On that note, you could probably save yourself some typing (no pun intended) by aliasing `Union[List[str], Tuple[str, ...]]` as, say, `IterableCollection`. ..."

_Originally posted by @falquaddoomi in https://github.com/cytomining/pycytominer-transform/pull/22#discussion_r1082906340_

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the interface documentation and the signatures of methods such as to_parquet(), then inspect the typing guidance linked in the issue and the original pull-request discussion. Define the scope of composability examples and named aliases before changing anything; done means the relevant public and private methods document their relationships and their signatures consistently expose the intended types.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.