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 (21,417 stars) (960 forks)batch import
good first issuehelp wanted

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

Tech stack
rust
Domain
documentationdeveloper experience
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.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Understanding of Gleam compiler architectureFamiliarity with internal modules config
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
20
Research direction
To implement this feature, you would need to add a check in the compiler's type checking phase to detect when a public function's signature uses a type from an internal module. Look at the compiler source in `src/` for the type checker and public API validation. The issue comments mention discussions about how to implement it. Start by understanding how internal modules are tracked and how private type errors are already emitted, then extend that logic.