Polish the API docs
Open
Nobody has claimed this yet.
A-docs
E-medium
- Dominant language
- Rust
- Stars
- 16.3k
- Forks
- 1.8k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 14
Description
This is issue about what appears at https://docs.rs/hyper. As a general rule, we should incrementally improve them with the following in mind:
- Types should have a description of what they are used for, not just a repeat of the type name.
- Methods should almost always include a code example.
- Modules should explain concepts of what its types are meant to be used for, and how to combine those types with others.
- If a question comes up more than once from a user, it should be somewhere in the API docs.
- If it is there, and people still ask, it's probably in the wrong place, or not written clearly.
Items to document
- lib 👀
- body
- #3299
- #3383
- client
- module: for the example, also link to the client guide.
-
conn: 👀
- ext
- module: explain that the types in here go in request or response extensions
- struct
Protocol: explain that it is for http/2, what it does, that it must be used with associated builder options, show example - struct
ReasonPhrase
- ffi: add
unstabletag - rt
- module: better overview, subsections explaining executors, timers, and IO
- server
-
connmodule: mention hyper-util providing anAutoConnectionand builder -
conn::http1module: provide an overview, and a getting started section - struct
conn::http1::Builder: Provide an example constructing one and setting some options. - struct
conn::http1::Connection: Explain that this is returned fromBuilder::serve_connection, and that it is essential animpl Futurethat must be polled (orawaited) for anything to happen. -
conn::http2module: provide an overview, and a getting started section
-
- service 👀
- upgrade 👀
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 with the unchecked sections in the hyper API docs on docs.rs, such as client, ext, rt, server, service, and upgrade, and choose one focused module or type. Review the existing documentation and related completed checklist items for style. Done means adding the requested overview, explanation, links, or code example for the selected item and checking it in the generated API docs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100