Docs gen internal modules · beginners

Stream: beginners

Topic: Docs gen internal modules

Luke Boswell (Jun 10 2023 at 04:43):

What should the behaviour be for a tag union that is imported from an "internal" module be? Should the tags be included in docs when we run roc docs?

Below is an example from basic-cli/blob/main/src/Dir.roc.

There is nothing generated for ReadErr in the docs. I guess we could manually include the types in a doc comment with ## but that seems like a bad idea for maintainability. I imagine users will want to know what the possible error types are so they can handle these if needed.

# In basic-cli/src/Dir.roc
ReadErr : InternalDir.ReadErr

# In basic-cli/src/InternalDir.roc
ReadErr : [
    NotFound,
    Interrupted,
    InvalidFilename,
    PermissionDenied,
    TooManySymlinks, # aka FilesystemLoop
    TooManyHardlinks,
    TimedOut,
    StaleNetworkFileHandle,
    NotADirectory,
    OutOfMemory,
    Unsupported,
    Unrecognized I32 Str,
]

Brendan Hansknecht (Jun 10 2023 at 05:00):

Do we need internal read error anymore

Brendan Hansknecht (Jun 10 2023 at 05:00):

I think it was needed to work around glue limitations at the time

Luke Boswell (Jun 10 2023 at 06:10):

Interesting, I wonder if that is the same for all of the InternalX modules? Or is this related to opaque types somehow? like maybe this is the way to "hide" implementation details.

Luke Boswell (Jun 10 2023 at 23:51):

@Richard Feldman do you have any thoughts on this? I can make some changes while I'm looking at this today.

Richard Feldman (Jun 11 2023 at 00:54):

Luke Boswell said:

Interesting, I wonder if that is the same for all of the InternalX modules? Or is this related to opaque types somehow? like maybe this is the way to "hide" implementation details.

yeah that's the point of InternalX - it's a way to say "my sibling modules can access this, but nobody outside our package can access it"

Richard Feldman (Jun 11 2023 at 00:55):

separately, before docs generation was aware of which modules were exported from a package, it had a hack that would look for the string "Internal" in the module name, and if it saw that, hide it from the docs :laughing:

Richard Feldman (Jun 11 2023 at 00:55):

but today it's actually aware of what's exposed, so that hack is gone

Brendan Hansknecht (Jun 11 2023 at 01:25):

Why wouldn't we want read error and related types as exposed types? Why are they internal?

Richard Feldman (Jun 11 2023 at 01:27):

oh, they are exposed - via Dir

interface Dir
    exposes [ReadErr, DeleteErr, DirEntry, deleteEmptyDir, deleteRecursive, list]
    imports [Effect, Task.{ Task }, InternalTask, Path.{ Path }, InternalPath, InternalDir]

ReadErr : InternalDir.ReadErr

Richard Feldman (Jun 11 2023 at 01:28):

another use of Internal is avoiding cyclic dependencies

Luke Boswell (Jun 11 2023 at 01:30):

Screen-Shot-2023-06-11-at-11.30.00.png

Richard Feldman (Jun 11 2023 at 01:30):

although I forget if there was a cyclic dep issue here that InternalDir was solving...it's been awhile since I've looked at that code! :big_smile:

Luke Boswell (Jun 11 2023 at 01:30):

This is what the docs looks like, I just feel like it would be good to see these errors enumerated. Otherwise a user will need to dig into the platform implementation to know what these are and handle them

Richard Feldman (Jun 11 2023 at 01:31):

oh yeah for sure

Richard Feldman (Jun 11 2023 at 01:31):

I think the issue here is just that docs gen is not doing what it ideally should

Luke Boswell (Jun 11 2023 at 01:32):

Ohk, so re-exporting something from a sibling "InternalX" package should be visible in the docs?

Richard Feldman (Jun 11 2023 at 01:33):

I think what it should do is:

if it's an exposed type alias of a type alias from an internal module, it should try to unpack the type alias and render whatever it resolves to (so the fact that it's a type alias becomes an implementation detail and isn't reflected in the docs
if, in the course of unpacking that type alias, it encounters a type that isn't exposed (e.g. because it's a type that isn't exposed from any module, or because it's exposed from an "internal-only" module that the package doesn't expose) then it renders nothing for the type, because that type is opaque to the reader of the docs by design

Luke Boswell (Jun 11 2023 at 01:34):

What about our opaque types? They should also render nothing I guess, even if they are exposed?

Richard Feldman (Jun 11 2023 at 01:35):

yeah opaque types should always render nothing :thumbs_up:

Brendan Hansknecht (Jun 11 2023 at 01:45):

Ok. Yeah, that makes sense.

Last updated: Jul 05 2025 at 12:14 UTC