Contribute Doctests to Tokio

[yoshuawuyts]

Contribute Doctests to Tokio

Summary

We propose to improve Tokio's documentation by adding doctests for each public
method.

Motivation

Tokio is a highly important library in Rust's ecosystem. It provides async
counterparts for many of stdlib's methods. However, unlike stdlib not every
method has usage examples yet (also known as doctests).

We propose to make a coordinated effort to track down missing usage examples,
and make pull requests to add them. This will hopefully both help people get
involved with Tokio, as help people new to the project find their way on how to
the libraries.

Implementation

I ran a script to find all pub fn names in tokio, and added them to the
overview at the end of this issue. To contribute a doctest:

1. Clone tokio-rs/tokio.
2. Choose a file from the overview.
3. Comment on this issue which file you've chosen to work on.
4. Write a few doctests for the file.
5. Read Tokio's contributing guidelines.
6. Make a PR, and link back to this issue.
7. Once the PR is approved, we can cross off doctests from the file.

Example from current documentation

Script

#!/bin/bash

base_url="https://github.com/tokio-rs/tokio"
curr_commit="cc3b6af7a3927751b12a82c61fae97b4cca30c12"

# Find all public methods
matches="$(rg -g '!names' --vimgrep 'pub fn' .)"
matches="$(echo "$matches" | grep -v main | grep -v tests | grep -v examples)"

# Get all method names, file names, and merge them on one line
fn_names="$(echo "$matches" | perl -nE '/pub fn (\w+)/ and say "$1";')"
line_nums="$(echo "$matches" | perl -nE '/\:(\d+)\:/ and say "$1";')"
lines="$(echo "$matches" | awk '{print $1}' | sed 's/\:.*$//')"
files="$(paste <(printf "$lines") <(printf "$fn_names") <(printf "$line_nums"))"

# Iterate over all file-method names combinations, and create a markdown list
echo "$files" | while read line; do
  file="$(echo "$line" | awk '{print $1}')"
  fn_name="$(echo "$line" | awk '{print $2}')"
  num="$(echo "$line" | awk '{print $3}')"
  url="$(printf '%s/blob/%s/%s#L%s' "$base_url" "$curr_commit" "$file" "$num")"
  echo "- [ ] [$file#$fn_name]($url)"
done

Drawbacks

There seems to be some duplication in the APIs between tokio and tokio-*
modules. If both modules are going to be merged, perhaps we should prioritize
one implementation first.

Secondly Tokio doesn't support futures@0.3.0 yet, which means async/await
support is in somewhat of a transitioning phase. This might be an argument to
hold off until tokio upgrades to futures@0.3.0. But there doesn't seem to be a
clear timeline yet for when such a transition might be done, and there seem to
be clear benefits to improve documentation today.

There are over 600 API methods in tokio. That means there's probably quite a
few examples to be written. Therefor helping out with reviewing doctest PRs
would be fantastic too!

Rationale and alternatives

The idea of doctests is that they exist in harmony with more tutorials and
examples. It does not replace any of the above, but instead makes the existing

Unresolved Questions

We should probably figure out which modules to prioritize to prevent duplicate
work.

---

cc/ @carllerche @seanmonstar Your input would be valued a lot!

Overview

Tokio

• src/length_delimited.rs#new
• src/length_delimited.rs#get_ref
• src/length_delimited.rs#get_mut
• src/length_delimited.rs#into_inner
• src/length_delimited.rs#new
• src/length_delimited.rs#max_frame_length
• src/length_delimited.rs#set_max_frame_length
• src/length_delimited.rs#get_ref
• src/length_delimited.rs#get_mut
• src/length_delimited.rs#into_inner
• src/length_delimited.rs#new
• src/length_delimited.rs#max_frame_length
• src/length_delimited.rs#set_max_frame_length
• src/length_delimited.rs#get_ref
• src/length_delimited.rs#get_mut
• src/length_delimited.rs#into_inner
• src/length_delimited.rs#new
• src/length_delimited.rs#big_endian
• src/length_delimited.rs#little_endian
• src/length_delimited.rs#native_endian
• src/length_delimited.rs#max_frame_length
• src/length_delimited.rs#length_field_length
• src/length_delimited.rs#length_field_offset
• src/length_delimited.rs#length_adjustment
• src/length_delimited.rs#num_skip
• src/length_delimited.rs#new_read
• src/length_delimited.rs#new_write
• src/length_delimited.rs#new_framed
• src/runtime/builder.rs#new
• src/runtime/builder.rs#clock
• src/runtime/builder.rs#threadpool_builder
• src/runtime/builder.rs#build
• src/runtime/task_executor.rs#spawn
• src/runtime/mod.rs#run
• src/runtime/mod.rs#new
• src/runtime/mod.rs#handle
• src/runtime/mod.rs#reactor
• src/runtime/mod.rs#executor
• src/runtime/mod.rs#spawn
• src/runtime/mod.rs#block_on
• src/runtime/mod.rs#block_on_all
• src/runtime/mod.rs#shutdown_on_idle
• src/runtime/mod.rs#shutdown_now
• src/reactor/poll_evented.rs#new
• src/reactor/poll_evented.rs#poll_read
• src/reactor/poll_evented.rs#poll_write
• src/reactor/poll_evented.rs#poll_ready
• src/reactor/poll_evented.rs#need_read
• src/reactor/poll_evented.rs#need_write
• src/reactor/poll_evented.rs#handle
• src/reactor/poll_evented.rs#get_ref
• src/reactor/poll_evented.rs#get_mut
• src/reactor/poll_evented.rs#into_inner
• src/reactor/poll_evented.rs#deregister
• src/reactor/poll_evented.rs#ready2usize
• src/reactor/poll_evented.rs#usize2ready
• src/reactor/poll_evented.rs#all
• src/reactor/poll_evented.rs#hup
• src/reactor/poll_evented.rs#ready2usize
• src/reactor/poll_evented.rs#usize2ready
• src/executor/current_thread/mod.rs#cancel_all_spawned
• src/executor/current_thread/mod.rs#run
• src/executor/current_thread/mod.rs#task_executor
• src/executor/mod.rs#spawn
• src/runtime/current_thread/builder.rs#new
• src/runtime/current_thread/builder.rs#clock
• src/runtime/current_thread/builder.rs#build
• src/runtime/current_thread/mod.rs#block_on_all
• src/runtime/current_thread/runtime.rs#spawn
• src/runtime/current_thread/runtime.rs#new
• src/runtime/current_thread/runtime.rs#handle
• src/runtime/current_thread/runtime.rs#spawn
• src/runtime/current_thread/runtime.rs#block_on
• src/runtime/current_thread/runtime.rs#run

tokio-channel

• tokio-channel/src/lock.rs#new
• tokio-channel/src/lock.rs#try_lock
• tokio-channel/src/oneshot.rs#channel
• tokio-channel/src/oneshot.rs#complete
• tokio-channel/src/oneshot.rs#send
• tokio-channel/src/oneshot.rs#poll_cancel
• tokio-channel/src/oneshot.rs#is_canceled
• tokio-channel/src/oneshot.rs#close
• tokio-channel/src/mpsc/queue.rs#new
• tokio-channel/src/mpsc/queue.rs#push
• tokio-channel/src/mpsc/mod.rs#into_inner
• tokio-channel/src/mpsc/mod.rs#is_full
• tokio-channel/src/mpsc/mod.rs#is_disconnected
• tokio-channel/src/mpsc/mod.rs#into_inner
• tokio-channel/src/mpsc/mod.rs#channel
• tokio-channel/src/mpsc/mod.rs#unbounded
• tokio-channel/src/mpsc/mod.rs#try_send
• tokio-channel/src/mpsc/mod.rs#poll_ready
• tokio-channel/src/mpsc/mod.rs#send
• tokio-channel/src/mpsc/mod.rs#unbounded_send
• tokio-channel/src/mpsc/mod.rs#close

tokio-codec

• tokio-codec/src/bytes_codec.rs#new
• tokio-codec/src/lines_codec.rs#new

tokio-executor

• tokio-executor/src/enter.rs#enter
• tokio-executor/src/enter.rs#on_exit
• tokio-executor/src/enter.rs#make_permanent
• tokio-executor/src/global.rs#current
• tokio-executor/src/global.rs#dox
• tokio-executor/src/global.rs#spawn
• tokio-executor/src/global.rs#with_default
• tokio-executor/src/lib.rs#shutdown
• tokio-executor/src/lib.rs#at_capacity
• tokio-executor/src/lib.rs#is_shutdown
• tokio-executor/src/lib.rs#is_at_capacity
• tokio-executor/src/park.rs#new

tokio-current-thread

• tokio-current-thread/src/scheduler.rs#new
• tokio-current-thread/src/scheduler.rs#notify
• tokio-current-thread/src/scheduler.rs#schedule
• tokio-current-thread/src/scheduler.rs#has_pending_futures
• tokio-current-thread/src/scheduler.rs#tick
• tokio-current-thread/src/scheduler.rs#tick
• tokio-current-thread/src/scheduler.rs#new
• tokio-current-thread/src/lib.rs#has_polled
• tokio-current-thread/src/lib.rs#block_on_all
• tokio-current-thread/src/lib.rs#spawn
• tokio-current-thread/src/lib.rs#new
• tokio-current-thread/src/lib.rs#new_with_park
• tokio-current-thread/src/lib.rs#is_idle
• tokio-current-thread/src/lib.rs#spawn
• tokio-current-thread/src/lib.rs#block_on
• tokio-current-thread/src/lib.rs#run
• tokio-current-thread/src/lib.rs#run_timeout
• tokio-current-thread/src/lib.rs#turn
• tokio-current-thread/src/lib.rs#enter
• tokio-current-thread/src/lib.rs#get_park
• tokio-current-thread/src/lib.rs#get_park_mut
• tokio-current-thread/src/lib.rs#handle
• tokio-current-thread/src/lib.rs#spawn
• tokio-current-thread/src/lib.rs#block_on
• tokio-current-thread/src/lib.rs#run
• tokio-current-thread/src/lib.rs#run_timeout
• tokio-current-thread/src/lib.rs#turn
• tokio-current-thread/src/lib.rs#get_park
• tokio-current-thread/src/lib.rs#get_park_mut
• tokio-current-thread/src/lib.rs#spawn
• tokio-current-thread/src/lib.rs#current
• tokio-current-thread/src/lib.rs#spawn_local
• tokio-current-thread/src/lib.rs#is_timeout
• tokio-current-thread/src/lib.rs#into_inner

tokio-fs

• tokio-fs/src/create_dir.rs#create_dir
• tokio-fs/src/create_dir_all.rs#create_dir_all
• tokio-fs/src/hard_link.rs#hard_link
• tokio-fs/src/metadata.rs#metadata
• tokio-fs/src/read_link.rs#read_link
• tokio-fs/src/read_dir.rs#read_dir
• tokio-fs/src/read_dir.rs#into_std
• tokio-fs/src/read_dir.rs#path
• tokio-fs/src/read_dir.rs#file_name
• tokio-fs/src/read_dir.rs#poll_metadata
• tokio-fs/src/read_dir.rs#poll_file_type
• tokio-fs/src/remove_dir.rs#remove_dir
• tokio-fs/src/remove_file.rs#remove_file
• tokio-fs/src/rename.rs#rename
• tokio-fs/src/set_permissions.rs#set_permissions
• tokio-fs/src/stderr.rs#stderr
• tokio-fs/src/stdin.rs#stdin
• tokio-fs/src/stdout.rs#stdout
• tokio-fs/src/symlink_metadata.rs#symlink_metadata

tokio-io

• tokio-io/src/allow_std.rs#new
• tokio-io/src/allow_std.rs#get_ref
• tokio-io/src/allow_std.rs#get_mut
• tokio-io/src/allow_std.rs#into_inner
• tokio-io/src/framed.rs#framed
• tokio-io/src/framed.rs#from_parts
• tokio-io/src/framed.rs#get_ref
• tokio-io/src/framed.rs#get_mut
• tokio-io/src/framed.rs#into_inner
• tokio-io/src/framed.rs#into_parts
• tokio-io/src/framed.rs#into_parts_and_codec
• tokio-io/src/framed_read.rs#new
• tokio-io/src/framed_read.rs#get_ref
• tokio-io/src/framed_read.rs#get_mut
• tokio-io/src/framed_read.rs#into_inner
• tokio-io/src/framed_read.rs#decoder
• tokio-io/src/framed_read.rs#decoder_mut
• tokio-io/src/framed_read.rs#framed_read2
• tokio-io/src/framed_read.rs#framed_read2_with_buffer
• tokio-io/src/framed_read.rs#get_ref
• tokio-io/src/framed_read.rs#into_inner
• tokio-io/src/framed_read.rs#into_parts
• tokio-io/src/framed_read.rs#get_mut
• tokio-io/src/framed_write.rs#new
• tokio-io/src/framed_write.rs#get_ref
• tokio-io/src/framed_write.rs#get_mut
• tokio-io/src/framed_write.rs#into_inner
• tokio-io/src/framed_write.rs#encoder
• tokio-io/src/framed_write.rs#encoder_mut
• tokio-io/src/framed_write.rs#framed_write2
• tokio-io/src/framed_write.rs#framed_write2_with_buffer
• tokio-io/src/framed_write.rs#get_ref
• tokio-io/src/framed_write.rs#into_inner
• tokio-io/src/framed_write.rs#into_parts
• tokio-io/src/framed_write.rs#get_mut
• tokio-io/src/lines.rs#lines
• tokio-io/src/lines.rs#into_inner
• tokio-io/src/split.rs#split
• tokio-io/src/length_delimited.rs#new
• tokio-io/src/length_delimited.rs#get_ref
• tokio-io/src/length_delimited.rs#get_mut
• tokio-io/src/length_delimited.rs#into_inner
• tokio-io/src/length_delimited.rs#new
• tokio-io/src/length_delimited.rs#max_frame_length
• tokio-io/src/length_delimited.rs#set_max_frame_length
• tokio-io/src/length_delimited.rs#get_ref
• tokio-io/src/length_delimited.rs#get_mut
• tokio-io/src/length_delimited.rs#into_inner
• tokio-io/src/length_delimited.rs#new
• tokio-io/src/length_delimited.rs#max_frame_length
• tokio-io/src/length_delimited.rs#set_max_frame_length
• tokio-io/src/length_delimited.rs#get_ref
• tokio-io/src/length_delimited.rs#get_mut
• tokio-io/src/length_delimited.rs#into_inner
• tokio-io/src/length_delimited.rs#new
• tokio-io/src/length_delimited.rs#big_endian
• tokio-io/src/length_delimited.rs#little_endian
• tokio-io/src/length_delimited.rs#native_endian
• tokio-io/src/length_delimited.rs#max_frame_length
• tokio-io/src/length_delimited.rs#length_field_length
• tokio-io/src/length_delimited.rs#length_field_offset
• tokio-io/src/length_delimited.rs#length_adjustment
• tokio-io/src/length_delimited.rs#num_skip
• tokio-io/src/length_delimited.rs#new_read
• tokio-io/src/length_delimited.rs#new_write
• tokio-io/src/length_delimited.rs#new_framed
• tokio-io/src/window.rs#new
• tokio-io/src/window.rs#get_ref
• tokio-io/src/window.rs#get_mut
• tokio-io/src/window.rs#into_inner
• tokio-io/src/window.rs#start
• tokio-io/src/window.rs#end
• tokio-io/src/window.rs#set_start
• tokio-io/src/window.rs#set_end

tokio-reactor

• tokio-reactor/src/background.rs#handle
• tokio-reactor/src/background.rs#shutdown_on_idle
• tokio-reactor/src/background.rs#shutdown_now
• tokio-reactor/src/background.rs#forget
• tokio-reactor/src/atomic_task.rs#new
• tokio-reactor/src/atomic_task.rs#register_task
• tokio-reactor/src/atomic_task.rs#take_to_notify
• tokio-reactor/src/atomic_task.rs#notify
• tokio-reactor/src/lib.rs#with_default
• tokio-reactor/src/lib.rs#new
• tokio-reactor/src/lib.rs#handle
• tokio-reactor/src/lib.rs#set_fallback
• tokio-reactor/src/lib.rs#turn
• tokio-reactor/src/lib.rs#is_idle
• tokio-reactor/src/lib.rs#background
• tokio-reactor/src/lib.rs#current
• tokio-reactor/src/lib.rs#hup
• tokio-reactor/src/lib.rs#is_hup
• tokio-reactor/src/lib.rs#hup
• tokio-reactor/src/lib.rs#is_hup
• tokio-reactor/src/poll_evented.rs#poll_accept
• tokio-reactor/src/poll_evented.rs#new
• tokio-reactor/src/poll_evented.rs#new_with_handle
• tokio-reactor/src/poll_evented.rs#get_ref
• tokio-reactor/src/poll_evented.rs#get_mut
• tokio-reactor/src/poll_evented.rs#into_inner
• tokio-reactor/src/poll_evented.rs#poll_read_ready
• tokio-reactor/src/poll_evented.rs#clear_read_ready
• tokio-reactor/src/poll_evented.rs#poll_write_ready
• tokio-reactor/src/poll_evented.rs#clear_write_ready
• tokio-reactor/src/registration.rs#new
• tokio-reactor/src/registration.rs#register
• tokio-reactor/src/registration.rs#deregister
• tokio-reactor/src/registration.rs#register_with
• tokio-reactor/src/registration.rs#poll_read_ready
• tokio-reactor/src/registration.rs#take_read_ready
• tokio-reactor/src/registration.rs#poll_write_ready
• tokio-reactor/src/registration.rs#take_write_ready
• tokio-reactor/src/sharded_rwlock.rs#new
• tokio-reactor/src/sharded_rwlock.rs#read
• tokio-reactor/src/sharded_rwlock.rs#write
• tokio-reactor/src/sharded_rwlock.rs#thread_index

tokio-tcp

• tokio-tcp/src/listener.rs#bind
• tokio-tcp/src/listener.rs#accept
• tokio-tcp/src/listener.rs#poll_accept
• tokio-tcp/src/listener.rs#accept_std
• tokio-tcp/src/listener.rs#poll_accept_std
• tokio-tcp/src/listener.rs#from_std
• tokio-tcp/src/listener.rs#local_addr
• tokio-tcp/src/listener.rs#incoming
• tokio-tcp/src/listener.rs#ttl
• tokio-tcp/src/listener.rs#set_ttl
• tokio-tcp/src/stream.rs#connect
• tokio-tcp/src/stream.rs#from_std
• tokio-tcp/src/stream.rs#connect_std
• tokio-tcp/src/stream.rs#poll_read_ready
• tokio-tcp/src/stream.rs#poll_write_ready
• tokio-tcp/src/stream.rs#local_addr
• tokio-tcp/src/stream.rs#peer_addr
• tokio-tcp/src/stream.rs#peek
• tokio-tcp/src/stream.rs#poll_peek
• tokio-tcp/src/stream.rs#shutdown
• tokio-tcp/src/stream.rs#nodelay
• tokio-tcp/src/stream.rs#set_nodelay
• tokio-tcp/src/stream.rs#recv_buffer_size
• tokio-tcp/src/stream.rs#set_recv_buffer_size
• tokio-tcp/src/stream.rs#send_buffer_size
• tokio-tcp/src/stream.rs#set_send_buffer_size
• tokio-tcp/src/stream.rs#keepalive
• tokio-tcp/src/stream.rs#set_keepalive
• tokio-tcp/src/stream.rs#ttl
• tokio-tcp/src/stream.rs#set_ttl
• tokio-tcp/src/stream.rs#linger
• tokio-tcp/src/stream.rs#set_linger
• tokio-tcp/src/stream.rs#try_clone

tokio-threadpool

• tokio-threadpool/src/blocking.rs#blocking
• tokio-threadpool/src/callback.rs#new
• tokio-threadpool/src/callback.rs#call
• tokio-threadpool/src/builder.rs#new
• tokio-threadpool/src/builder.rs#pool_size
• tokio-threadpool/src/builder.rs#max_blocking
• tokio-threadpool/src/builder.rs#keep_alive
• tokio-threadpool/src/builder.rs#name_prefix
• tokio-threadpool/src/builder.rs#stack_size
• tokio-threadpool/src/builder.rs#around_worker
• tokio-threadpool/src/builder.rs#after_start
• tokio-threadpool/src/builder.rs#before_stop
• tokio-threadpool/src/builder.rs#custom_park
• tokio-threadpool/src/builder.rs#build
• tokio-threadpool/src/sender.rs#spawn
• tokio-threadpool/src/shutdown_task.rs#notify
• tokio-threadpool/src/thread_pool.rs#new
• tokio-threadpool/src/thread_pool.rs#spawn
• tokio-threadpool/src/thread_pool.rs#sender
• tokio-threadpool/src/thread_pool.rs#sender_mut
• tokio-threadpool/src/thread_pool.rs#shutdown_on_idle
• tokio-threadpool/src/thread_pool.rs#shutdown
• tokio-threadpool/src/thread_pool.rs#shutdown_now

tokio-timer

• tokio-timer/src/atomic.rs#new
• tokio-timer/src/atomic.rs#load
• tokio-timer/src/atomic.rs#store
• tokio-timer/src/atomic.rs#fetch_or
• tokio-timer/src/atomic.rs#compare_and_swap
• tokio-timer/src/atomic.rs#new
• tokio-timer/src/atomic.rs#load
• tokio-timer/src/atomic.rs#store
• tokio-timer/src/atomic.rs#fetch_or
• tokio-timer/src/atomic.rs#compare_and_swap
• tokio-timer/src/deadline.rs#new
• tokio-timer/src/deadline.rs#get_ref
• tokio-timer/src/deadline.rs#get_mut
• tokio-timer/src/deadline.rs#into_inner
• tokio-timer/src/deadline.rs#inner
• tokio-timer/src/deadline.rs#is_inner
• tokio-timer/src/deadline.rs#into_inner
• tokio-timer/src/deadline.rs#elapsed
• tokio-timer/src/deadline.rs#is_elapsed
• tokio-timer/src/deadline.rs#timer
• tokio-timer/src/deadline.rs#is_timer
• tokio-timer/src/deadline.rs#into_timer
• tokio-timer/src/delay.rs#new
• tokio-timer/src/delay.rs#deadline
• tokio-timer/src/delay.rs#is_elapsed
• tokio-timer/src/delay.rs#reset
• tokio-timer/src/error.rs#shutdown
• tokio-timer/src/error.rs#is_shutdown
• tokio-timer/src/error.rs#at_capacity
• tokio-timer/src/error.rs#is_at_capacity
• tokio-timer/src/delay_queue.rs#new
• tokio-timer/src/delay_queue.rs#with_capacity_and_handle
• tokio-timer/src/delay_queue.rs#with_capacity
• tokio-timer/src/delay_queue.rs#insert_at
• tokio-timer/src/delay_queue.rs#insert
• tokio-timer/src/delay_queue.rs#remove
• tokio-timer/src/delay_queue.rs#reset_at
• tokio-timer/src/delay_queue.rs#reset
• tokio-timer/src/delay_queue.rs#clear
• tokio-timer/src/delay_queue.rs#capacity
• tokio-timer/src/delay_queue.rs#reserve
• tokio-timer/src/delay_queue.rs#is_empty
• tokio-timer/src/delay_queue.rs#get_ref
• tokio-timer/src/delay_queue.rs#get_mut
• tokio-timer/src/delay_queue.rs#into_inner
• tokio-timer/src/interval.rs#new
• tokio-timer/src/interval.rs#new_interval
• tokio-timer/src/lib.rs#sleep
• tokio-timer/src/timeout.rs#new
• tokio-timer/src/timeout.rs#get_ref
• tokio-timer/src/timeout.rs#get_mut
• tokio-timer/src/timeout.rs#into_inner
• tokio-timer/src/timeout.rs#new_at
• tokio-timer/src/timeout.rs#inner
• tokio-timer/src/timeout.rs#is_inner
• tokio-timer/src/timeout.rs#into_inner
• tokio-timer/src/timeout.rs#elapsed
• tokio-timer/src/timeout.rs#is_elapsed
• tokio-timer/src/timeout.rs#timer
• tokio-timer/src/timeout.rs#is_timer
• tokio-timer/src/timeout.rs#into_timer

tokio-tls

• tokio-tls/src/lib.rs#get_ref
• tokio-tls/src/lib.rs#get_mut
• tokio-tls/src/lib.rs#accept

tokio-udp

• tokio-udp/src/frame.rs#new
• tokio-udp/src/frame.rs#get_ref
• tokio-udp/src/frame.rs#get_mut
• tokio-udp/src/frame.rs#into_inner
• tokio-udp/src/socket.rs#bind
• tokio-udp/src/socket.rs#from_std
• tokio-udp/src/socket.rs#local_addr
• tokio-udp/src/socket.rs#connect
• tokio-udp/src/socket.rs#send
• tokio-udp/src/socket.rs#poll_send
• tokio-udp/src/socket.rs#recv
• tokio-udp/src/socket.rs#poll_recv
• tokio-udp/src/socket.rs#send_to
• tokio-udp/src/socket.rs#poll_send_to
• tokio-udp/src/socket.rs#send_dgram
• tokio-udp/src/socket.rs#recv_from
• tokio-udp/src/socket.rs#poll_recv_from
• tokio-udp/src/socket.rs#recv_dgram
• tokio-udp/src/socket.rs#poll_read_ready
• tokio-udp/src/socket.rs#poll_write_ready
• tokio-udp/src/socket.rs#broadcast
• tokio-udp/src/socket.rs#set_broadcast
• tokio-udp/src/socket.rs#multicast_loop_v4
• tokio-udp/src/socket.rs#set_multicast_loop_v4
• tokio-udp/src/socket.rs#multicast_ttl_v4
• tokio-udp/src/socket.rs#set_multicast_ttl_v4
• tokio-udp/src/socket.rs#multicast_loop_v6
• tokio-udp/src/socket.rs#set_multicast_loop_v6
• tokio-udp/src/socket.rs#ttl
• tokio-udp/src/socket.rs#set_ttl
• tokio-udp/src/socket.rs#join_multicast_v4
• tokio-udp/src/socket.rs#join_multicast_v6
• tokio-udp/src/socket.rs#leave_multicast_v4
• tokio-udp/src/socket.rs#leave_multicast_v6

tokio-uds

• tokio-uds/src/datagram.rs#bind
• tokio-uds/src/datagram.rs#pair
• tokio-uds/src/datagram.rs#from_std
• tokio-uds/src/datagram.rs#unbound
• tokio-uds/src/datagram.rs#connect
• tokio-uds/src/datagram.rs#poll_read_ready
• tokio-uds/src/datagram.rs#poll_write_ready
• tokio-uds/src/datagram.rs#local_addr
• tokio-uds/src/datagram.rs#peer_addr
• tokio-uds/src/datagram.rs#poll_recv_from
• tokio-uds/src/datagram.rs#poll_recv
• tokio-uds/src/datagram.rs#recv_dgram
• tokio-uds/src/datagram.rs#poll_send_to
• tokio-uds/src/datagram.rs#poll_send
• tokio-uds/src/datagram.rs#send_dgram
• tokio-uds/src/datagram.rs#take_error
• tokio-uds/src/datagram.rs#shutdown
• tokio-uds/src/listener.rs#bind
• tokio-uds/src/listener.rs#from_std
• tokio-uds/src/listener.rs#local_addr
• tokio-uds/src/listener.rs#poll_read_ready
• tokio-uds/src/listener.rs#take_error
• tokio-uds/src/listener.rs#poll_accept
• tokio-uds/src/listener.rs#poll_accept_std
• tokio-uds/src/listener.rs#incoming
• tokio-uds/src/ucred.rs#get_peer_cred
• tokio-uds/src/ucred.rs#get_peer_cred
• tokio-uds/src/stream.rs#connect
• tokio-uds/src/stream.rs#from_std
• tokio-uds/src/stream.rs#pair
• tokio-uds/src/stream.rs#poll_read_ready
• tokio-uds/src/stream.rs#poll_write_ready
• tokio-uds/src/stream.rs#local_addr
• tokio-uds/src/stream.rs#peer_addr
• tokio-uds/src/stream.rs#peer_cred
• tokio-uds/src/stream.rs#take_error
• tokio-uds/src/stream.rs#shutdown

tokio-io

• tokio-io/src/_tokio_codec/framed.rs#from_parts
• tokio-io/src/_tokio_codec/framed.rs#get_mut
• tokio-io/src/_tokio_codec/framed.rs#get_ref
• tokio-io/src/_tokio_codec/framed.rs#into_inner
• tokio-io/src/_tokio_codec/framed.rs#into_parts
• tokio-io/src/_tokio_codec/framed.rs#new
• tokio-io/src/_tokio_codec/framed.rs#new
• tokio-io/src/_tokio_codec/framed_read.rs#decoder
• tokio-io/src/_tokio_codec/framed_read.rs#decoder_mut
• tokio-io/src/_tokio_codec/framed_read.rs#framed_read2
• tokio-io/src/_tokio_codec/framed_read.rs#framed_read2_with_buffer
• tokio-io/src/_tokio_codec/framed_read.rs#get_mut
• tokio-io/src/_tokio_codec/framed_read.rs#get_mut
• tokio-io/src/_tokio_codec/framed_read.rs#get_ref
• tokio-io/src/_tokio_codec/framed_read.rs#get_ref
• tokio-io/src/_tokio_codec/framed_read.rs#into_inner
• tokio-io/src/_tokio_codec/framed_read.rs#into_inner
• tokio-io/src/_tokio_codec/framed_read.rs#into_parts
• tokio-io/src/_tokio_codec/framed_read.rs#new
• tokio-io/src/_tokio_codec/framed_write.rs#encoder
• tokio-io/src/_tokio_codec/framed_write.rs#encoder_mut
• tokio-io/src/_tokio_codec/framed_write.rs#framed_write2
• tokio-io/src/_tokio_codec/framed_write.rs#framed_write2_with_buffer
• tokio-io/src/_tokio_codec/framed_write.rs#get_mut
• tokio-io/src/_tokio_codec/framed_write.rs#get_mut
• tokio-io/src/_tokio_codec/framed_write.rs#get_ref
• tokio-io/src/_tokio_codec/framed_write.rs#get_ref
• tokio-io/src/_tokio_codec/framed_write.rs#into_inner
• tokio-io/src/_tokio_codec/framed_write.rs#into_inner
• tokio-io/src/_tokio_codec/framed_write.rs#into_parts
• tokio-io/src/_tokio_codec/framed_write.rs#new
• tokio-io/src/codec/bytes_codec.rs#new
• tokio-io/src/codec/lines_codec.rs#new
• tokio-io/src/io/copy.rs#copy
• tokio-io/src/io/flush.rs#flush
• tokio-io/src/io/read.rs#read
• tokio-io/src/io/read_exact.rs#read_exact
• tokio-io/src/io/read_to_end.rs#read_to_end
• tokio-io/src/io/read_until.rs#read_until
• tokio-io/src/io/shutdown.rs#shutdown
• tokio-io/src/io/write_all.rs#write_all

tokio-threadpool

• tokio-threadpool/src/park/boxed.rs#new
• tokio-threadpool/src/park/default_park.rs#new
• tokio-threadpool/src/pool/backup_stack.rs#new
• tokio-threadpool/src/pool/backup_stack.rs#push
• tokio-threadpool/src/pool/backup_stack.rs#pop
• tokio-threadpool/src/pool/backup.rs#new
• tokio-threadpool/src/pool/backup.rs#start
• tokio-threadpool/src/pool/backup.rs#is_running
• tokio-threadpool/src/pool/backup.rs#worker_handoff
• tokio-threadpool/src/pool/backup.rs#signal_stop
• tokio-threadpool/src/pool/backup.rs#release
• tokio-threadpool/src/pool/backup.rs#wait_for_handoff
• tokio-threadpool/src/pool/backup.rs#is_pushed
• tokio-threadpool/src/pool/backup.rs#set_pushed
• tokio-threadpool/src/pool/backup.rs#next_sleeper
• tokio-threadpool/src/pool/backup.rs#set_next_sleeper
• tokio-threadpool/src/pool/backup.rs#new
• tokio-threadpool/src/pool/backup.rs#is_pushed
• tokio-threadpool/src/pool/backup.rs#set_pushed
• tokio-threadpool/src/pool/backup.rs#is_running
• tokio-threadpool/src/pool/backup.rs#set_running
• tokio-threadpool/src/pool/backup.rs#unset_running
• tokio-threadpool/src/pool/backup.rs#is_terminated
• tokio-threadpool/src/pool/mod.rs#new
• tokio-threadpool/src/pool/mod.rs#shutdown
• tokio-threadpool/src/pool/mod.rs#is_shutdown
• tokio-threadpool/src/pool/mod.rs#push_sleeper
• tokio-threadpool/src/pool/mod.rs#terminate_sleeping_workers
• tokio-threadpool/src/pool/mod.rs#poll_blocking_capacity
• tokio-threadpool/src/pool/mod.rs#submit
• tokio-threadpool/src/pool/mod.rs#submit_external
• tokio-threadpool/src/pool/mod.rs#release_backup
• tokio-threadpool/src/pool/mod.rs#notify_blocking_task
• tokio-threadpool/src/pool/mod.rs#spawn_thread
• tokio-threadpool/src/pool/mod.rs#signal_work
• tokio-threadpool/src/pool/mod.rs#rand_usize
• tokio-threadpool/src/pool/state.rs#new
• tokio-threadpool/src/pool/state.rs#num_futures
• tokio-threadpool/src/pool/state.rs#inc_num_futures
• tokio-threadpool/src/pool/state.rs#dec_num_futures
• tokio-threadpool/src/pool/state.rs#clear_num_futures
• tokio-threadpool/src/pool/state.rs#lifecycle
• tokio-threadpool/src/pool/state.rs#set_lifecycle
• tokio-threadpool/src/pool/state.rs#is_terminated
• tokio-threadpool/src/task/blocking.rs#new
• tokio-threadpool/src/task/blocking.rs#poll_blocking_capacity
• tokio-threadpool/src/task/blocking.rs#notify_task
• tokio-threadpool/src/task/blocking_state.rs#new
• tokio-threadpool/src/task/blocking_state.rs#is_queued
• tokio-threadpool/src/task/blocking_state.rs#toggle_queued
• tokio-threadpool/src/task/blocking_state.rs#is_allocated
• tokio-threadpool/src/task/blocking_state.rs#consume_allocation
• tokio-threadpool/src/task/blocking_state.rs#notify_blocking
• tokio-threadpool/src/worker/entry.rs#new
• tokio-threadpool/src/worker/entry.rs#load_state
• tokio-threadpool/src/worker/entry.rs#fetch_unset_pushed
• tokio-threadpool/src/worker/entry.rs#submit_internal
• tokio-threadpool/src/worker/entry.rs#submit_external
• tokio-threadpool/src/worker/entry.rs#signal_stop
• tokio-threadpool/src/worker/entry.rs#pop_task
• tokio-threadpool/src/worker/entry.rs#steal_tasks
• tokio-threadpool/src/worker/entry.rs#drain_tasks
• tokio-threadpool/src/worker/entry.rs#push_internal
• tokio-threadpool/src/worker/entry.rs#wakeup
• tokio-threadpool/src/worker/entry.rs#next_sleeper
• tokio-threadpool/src/worker/entry.rs#set_next_sleeper
• tokio-threadpool/src/task/mod.rs#new
• tokio-threadpool/src/task/mod.rs#run
• tokio-threadpool/src/task/mod.rs#notify
• tokio-threadpool/src/task/mod.rs#notify_blocking
• tokio-threadpool/src/task/mod.rs#schedule
• tokio-threadpool/src/task/mod.rs#consume_blocking_allocation
• tokio-threadpool/src/task/queue.rs#new
• tokio-threadpool/src/task/queue.rs#push
• tokio-threadpool/src/task/state.rs#new
• tokio-threadpool/src/task/state.rs#stub
• tokio-threadpool/src/worker/mod.rs#id
• tokio-threadpool/src/worker/mod.rs#run
• tokio-threadpool/src/worker/stack.rs#new
• tokio-threadpool/src/worker/stack.rs#push
• tokio-threadpool/src/worker/stack.rs#pop
• tokio-threadpool/src/worker/state.rs#is_pushed
• tokio-threadpool/src/worker/state.rs#set_pushed
• tokio-threadpool/src/worker/state.rs#is_notified
• tokio-threadpool/src/worker/state.rs#lifecycle
• tokio-threadpool/src/worker/state.rs#set_lifecycle
• tokio-threadpool/src/worker/state.rs#is_signaled
• tokio-threadpool/src/worker/state.rs#notify

tokio-timer

• tokio-timer/src/clock/clock.rs#now
• tokio-timer/src/clock/clock.rs#new
• tokio-timer/src/clock/clock.rs#new_with_now
• tokio-timer/src/clock/clock.rs#system
• tokio-timer/src/clock/clock.rs#now
• tokio-timer/src/clock/clock.rs#with_default
• tokio-timer/src/timer/atomic_stack.rs#new
• tokio-timer/src/timer/atomic_stack.rs#push
• tokio-timer/src/timer/atomic_stack.rs#take
• tokio-timer/src/timer/atomic_stack.rs#shutdown
• tokio-timer/src/timer/entry.rs#new
• tokio-timer/src/timer/entry.rs#time_ref
• tokio-timer/src/timer/entry.rs#time_mut
• tokio-timer/src/timer/entry.rs#is_registered
• tokio-timer/src/timer/entry.rs#register
• tokio-timer/src/timer/entry.rs#register_with
• tokio-timer/src/timer/entry.rs#when_internal
• tokio-timer/src/timer/entry.rs#set_when_internal
• tokio-timer/src/timer/entry.rs#load_state
• tokio-timer/src/timer/entry.rs#is_elapsed
• tokio-timer/src/timer/entry.rs#fire
• tokio-timer/src/timer/entry.rs#error
• tokio-timer/src/timer/entry.rs#cancel
• tokio-timer/src/timer/entry.rs#poll_elapsed
• tokio-timer/src/timer/entry.rs#reset
• tokio-timer/src/timer/handle.rs#with_default
• tokio-timer/src/timer/handle.rs#current
• tokio-timer/src/timer/handle.rs#delay
• tokio-timer/src/timer/handle.rs#deadline
• tokio-timer/src/timer/handle.rs#interval
• tokio-timer/src/timer/mod.rs#new
• tokio-timer/src/timer/mod.rs#get_park
• tokio-timer/src/timer/mod.rs#get_park_mut
• tokio-timer/src/timer/mod.rs#new_with_now
• tokio-timer/src/timer/mod.rs#handle
• tokio-timer/src/timer/mod.rs#turn
• tokio-timer/src/wheel/level.rs#new
• tokio-timer/src/wheel/level.rs#next_expiration
• tokio-timer/src/wheel/level.rs#add_entry
• tokio-timer/src/wheel/level.rs#remove_entry
• tokio-timer/src/wheel/level.rs#pop_entry_slot
• tokio-timer/src/timer/registration.rs#new
• tokio-timer/src/timer/registration.rs#deadline
• tokio-timer/src/timer/registration.rs#register
• tokio-timer/src/timer/registration.rs#register_with
• tokio-timer/src/timer/registration.rs#reset
• tokio-timer/src/timer/registration.rs#reset_timeout
• tokio-timer/src/timer/registration.rs#is_elapsed
• tokio-timer/src/timer/registration.rs#poll_elapsed
• tokio-timer/src/wheel/mod.rs#new
• tokio-timer/src/wheel/mod.rs#elapsed
• tokio-timer/src/wheel/mod.rs#insert
• tokio-timer/src/wheel/mod.rs#remove
• tokio-timer/src/wheel/mod.rs#poll_at
• tokio-timer/src/wheel/mod.rs#poll
• tokio-timer/src/wheel/mod.rs#poll_expiration
• tokio-timer/src/wheel/mod.rs#new

tokio-async-await

• tokio-async-await/src/async_await/compat/backward.rs#new
• tokio-async-await/src/lib.rs#run_async
• tokio-async-await/src/lib.rs#spawn_async

tokio-fs

• tokio-fs/src/os/unix.rs#symlink
• tokio-fs/src/os/windows/symlink_dir.rs#symlink_dir
• tokio-fs/src/os/windows/symlink_file.rs#symlink_file
• tokio-fs/src/file/mod.rs#open
• tokio-fs/src/file/mod.rs#create
• tokio-fs/src/file/mod.rs#poll_seek
• tokio-fs/src/file/mod.rs#seek
• tokio-fs/src/file/mod.rs#poll_sync_all
• tokio-fs/src/file/mod.rs#poll_sync_data
• tokio-fs/src/file/mod.rs#poll_set_len
• tokio-fs/src/file/mod.rs#metadata
• tokio-fs/src/file/mod.rs#poll_metadata
• tokio-fs/src/file/mod.rs#poll_try_clone
• tokio-fs/src/file/mod.rs#poll_set_permissions
• tokio-fs/src/file/mod.rs#into_std
• tokio-fs/src/file/open_options.rs#new
• tokio-fs/src/file/open_options.rs#read
• tokio-fs/src/file/open_options.rs#write
• tokio-fs/src/file/open_options.rs#append
• tokio-fs/src/file/open_options.rs#truncate
• tokio-fs/src/file/open_options.rs#create
• tokio-fs/src/file/open_options.rs#create_new
• tokio-fs/src/file/open_options.rs#open

[Thomasdezeeuw]

Why is this not an issue in the tokio repo?

[yoshuawuyts]

@Thomasdezeeuw good question! I guess it's mostly because I was approaching it from a Net WG perspective, but you're right that it would also have worked as an issue on Tokio. I'm not sure which one works best, but open for arguments pro / con.

[carllerche]

@yoshuawuyts I added a doc test section to the contributing guide:

https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md#documentation-tests

[yoshuawuyts]

@carllerche thanks so much; it looks great!