Clarify Public vs Internal API Surface in Documentation #240
Description
Problem
It is currently unclear from the README and package documentation which exported functions/types are supported as public APIs, and which are internal implementations that happen to be exported (and may change without notice).
- Users and contributors lack guidance on what parts of each npm package can be safely relied on for long-term usage.
- This can lead to accidental dependence on internal or unstable APIs, resulting in future breakages.
Suggested Improvements
- Explicitly document which exports are considered the publicly supported API (with semver guarantees).
- Mark internal-but-exported symbols as such, with clear guidance that they can change or be removed at any time.
- Consider using JSDoc
@internalor similar tags in source code to further clarify intent. - Add a summary section in each package's README (especially for
@actions/expressions, etc.) listing the public API surface. - Reference this documentation from the top-level README.
Motivation
Clear API surface documentation helps external consumers use the packages safely and enhances overall maintainability.