hyperium / hyperium/hyper

Polish the API docs

Open
#3,067 3 comments 0 reactions 0 assignees View on GitHub

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 unstable tag
  • rt
    • module: better overview, subsections explaining executors, timers, and IO
  • server
    • conn module: mention hyper-util providing an AutoConnection and builder
    • conn::http1 module: 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 from Builder::serve_connection, and that it is essential an impl Future that must be polled (or awaited) for anything to happen.
    • conn::http2 module: provide an overview, and a getting started section
  • service 👀
  • upgrade 👀

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.