Update README with new function documentation#1
Update README with new function documentation#1DarkLord017 wants to merge 6 commits into0-th:dev(wip)from
Conversation
Added documentation for abort, all_, and batch functions.
|
@0-th started working on documentation pls review n lmk |
0-th
left a comment
0-th
left a comment
There was a problem hiding this comment.
Great effort here @DarkLord017 . I appreciate it.
I'd merge this right away once you've made necessary changes.
Also, I'd prefer if you didn't just pull in-code comments into the readme for documentation of the library APIs, and instead just documented similar to the reference implementation. see here.
I think the documentation would overall be much improved if the library was documented (not strictly or per-word) similarly to the reference implementation. At least it would be a really good start, coupled with the changes I requested in my review.
Thanks for the effort again.
README.md
Outdated
| # Class refrences | ||
|
|
||
| An implementation of [actor](https://github.com/Gozala/actor) in Python. | ||
| ## Future |
There was a problem hiding this comment.
the Future_ class was only meant to be inherited by the Fork class to make it await-able, it doesn't serve any other purposes outside of this.
doesn't need to be documented on here.
| ## Future | ||
| Provides Promise-like interface for tasks, enabling them to be awaited from async contexts. | ||
|
|
||
| ## Install |
There was a problem hiding this comment.
I think install instructions should be retained in the docs, but since it's yet to be published on PyPI, it could be edited later as the package name on PyPI might be subject to change
README.md
Outdated
|
|
||
| An implementation of [actor](https://github.com/Gozala/actor) in Python. | ||
| ## Future | ||
| Provides Promise-like interface for tasks, enabling them to be awaited from async contexts. |
There was a problem hiding this comment.
| Provides Promise-like interface for tasks, enabling them to be awaited from async contexts. |
| # actress | ||
| # Class refrences | ||
|
|
||
| An implementation of [actor](https://github.com/Gozala/actor) in Python. |
There was a problem hiding this comment.
I think this description should be kept as well. seems accurate to me.
README.md
Outdated
| **Abort handling:** | ||
| ```python | ||
| # Abort all idle tasks and re-enqueue them | ||
| for task in group.stack.idle: | ||
| yield from abort(task, error) | ||
| enqueue(task) | ||
| ``` |
There was a problem hiding this comment.
| **Abort handling:** | |
| ```python | |
| # Abort all idle tasks and re-enqueue them | |
| for task in group.stack.idle: | |
| yield from abort(task, error) | |
| enqueue(task) | |
| ``` |
README.md
Outdated
|
|
||
| Idle tasks may still have cleanup code (finally blocks), so: | ||
| - They are aborted | ||
| - Then re-enqueued so the abort fully completes |
There was a problem hiding this comment.
| Idle tasks may still have cleanup code (finally blocks), so: | |
| - They are aborted | |
| - Then re-enqueued so the abort fully completes |
| # {"type": "read", "read": "read2"} | ||
| ``` | ||
|
|
||
| ## Usage |
There was a problem hiding this comment.
I think you should keep the Usage section as well as it adds expected structure you'd find in documentations of Python libraries, similar reason to why I think you should keep the Installation section as well
| main(run_all()) | ||
| ``` | ||
|
|
||
| ## Contributing |
There was a problem hiding this comment.
I think you should add a general contribution guideline too.
e.g to install dev dependencies run: pip install -e ".[dev]", run tests: pytest, etc... things like that
| All welcome! storacha.network is open-source. | ||
|
|
||
| ## License | ||
|
|
||
| Dual-licensed under [Apache-2.0 OR MIT](LICENSE.md) |
There was a problem hiding this comment.
I think you should retain the original licensing as well as we'll ultimately still be getting this branch merged into the main repo in the storacha org.
2 participants
Adding documentation