Skip to content

add __private modules #4

@Radvendii

Description

@Radvendii

We have two related issues:

  1. A bunch of implementation details cannot be made private, since they must be used from one of the other crates (e.g. Values are defined in the value module but used from eval_state
  2. While we don't want users to need to use these features, it may be good to provide escape hatches so they can interface with the raw API if they need more control.

Problem (1) has been solved in other crates with a __private module with #[doc(hidden)] set. See for instance:

Alternatively we could probably just #[doc(hidden)] specific functions, but that seems messier to me.

Question: what if there are e.g. specific fields in a struct, or functions on a struct that operate this way (that cannot be separated out into a different module). Does this happen?

For problem (2), I brainstormed some solutions:

  1. Don't specifically solve it. Users can in theory use the things in __private. The problem with this is that (a) it's not documented and (b) rust users will expect __private to contain implementation details that are subject to change.
  2. Name the module something like internal instead. This sends a different signal. The problem with this is that there's no way to mark that something is just an implementation detail that's not part of the API and subject to change. Maybe this isn't an issue, because we should have stability in the interface between our internal crates anyways. In other words, any implementation details subject to change should actually be private and restricted to a single crate.
  3. Have both a __private module and an internal module. This just seems noisy and a bit confusing to me, but if we really do need some things to be subject to change and used within multiple crates, and other things to be not generally used but still accessible if need be, this might be the right solution.
  4. Anything that's not-generally-used but still accessible should be part of the normal module and just clearly documented as "not generally used"

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions