mkitti
July 10, 2022, 7:27am
56
Whether a function is exported or not does not by itself indicate whether it is public API or not. The main indicator if it is public API is whether it had a docstring and is included in the manual. If it is documented and the documentation does not say otherwise, it is public API.
There have been some efforts to explicitly declare components to be public API. One example is this issue:
opened 09:59PM - 03 Sep 21 UTC
closed 11:23PM - 27 Sep 23 UTC
packages
design
modules
## Summary
I would like to give package developers a way to declare names tha… t are part of their package's public API without needing to `export` them.
This feature request has two parts:
1. The `Base.@public` macro, which declares a name as public without `export`ing it.
2. The `Base.public_not_exported(m::Module)::Vector{Symbol}` function, which returns the list of all non-exported public names in the module `m`.
This feature request is non-breaking. Therefore, it can be implemented in a Julia 1.x release.
## Part 1: `Base.@public` macro
For example, suppose that my package has a public function named fit. Because that word is so common, I don't want to export it from my package. But I want to indicate that it is part of the public API in a structured way that downstream tools (Documenter.jl, JuliaHub, editors/IDEs, etc.) can understand.
So in this example, I could do something like the following:
```julia
module Foo
export cool_stuff # public and exported
@public fit # public but not exported
function cool_stuff end
function fit end
function private_stuff end # private
end # module
```
## Part 2:`Base.public_not_exported` function
The signature of the function will be: `Base.public_not_exported(m::Module)::Vector{Symbol}`.
Example usage:
```julia
julia> Base.public_not_exported(Foo)
1-element Vector{Symbol}:
:fit
```
## Related Discussions
There is some related discussion in https://github.com/JuliaDocs/Documenter.jl/pull/1507. However, I really want this to be something that any tool can use, so I don't want it to be specific to Documenter.
And this package:https://docs.juliahub.com/PublicAPI/Jfs06/0.1.0/
1 Like