async-rs / async-rs/async-std

Where should we put macros?

Open
#351 1 comment 0 reactions 0 assignees View on GitHub
api design feedback wanted question/feedback
Dominant language
Rust
Stars
4.1k
Forks
339
PR merge metrics
No merged PRs in 30d

Description

Consider the following macros:
- `async_std::task_local`
- `async_std::println`
- `async_std::task::ready`

They are not organized in a very sensible way. Why would `task_local` be in the root module and not in the `task` module? And why is `println` not in the `io` module if standard I/O functionality lives there?

In the Rust standard library, all macros live in the root module. This is perhaps a historical artifact because macros couldn't be placed anywhere else until Rust 2018 (remember the age of `#[macro_use]`?). If the standard library was designed today, perhaps we'd have `std::io::println` instead of `std::println`.

So we're facing a dilemma: do we organize our macros in `async_std` more logically (unlike `std`) or just dump them all in the root module (like `std`)? Or, do we keep the current situation and have equivalents of macros from `std` in the root module and place other macros elsewhere?

Macros in the root module are also re-exported in the prelude (just like in `std`). However, other macros aren't.

Opinions?

Contributor guide

Open the contributing guide

Research direction

Start by locating the exports for async_std::task_local, async_std::println, and async_std::task::ready, then compare their current module and prelude organization with the Rust standard library. Done means the project has a decided, consistent macro-placement policy and the affected exports and documentation reflect it.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.