gleam-lang/gleam

✨ Warn about internal types used in the public API.

Open

#2,234 opened on Jun 20, 2023

View on GitHub
 (9 comments) (3 reactions) (0 assignees)Rust (960 forks)batch import
good first issuehelp wanted

Repository metrics

Stars
 (21,417 stars)
PR merge metrics
 (Avg merge 10d 19h) (69 merged PRs in 30d)

Description

The internal_modules property in our gleam.toml config lets us define modules that won't be documented when generating gleam's package docs. Because gleam has no formal notion of "internal" modules, these modules can still be imported and used freely.

This is all well and good until a function in a package refers to an internal type:

pub fn with_handler(func: fn(Message, Subject(HandlerMessage)) ->
    Result(Nil, Nil)) -> WebsocketHandler

Here WebsocketHandler is an internal type and so has no documentation. The DX is very poor in this case, I had to dig into the source to work out where it was coming from!

It would be great if this emitted an error the same way that using a private type in the public API does, but I'd settle for a warning too ^.^

Contributor guide

Research direction
Investigate where the compiler checks for private types in public APIs, and extend that logic to also check for types from internal modules (defined in `internal modules`) and emit a warning or error.
Tech stack
rust
Domain
tooling
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
RustGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60