What does `public func` say about the methods of `func`?

[nsajko]

public some_name marks some_name as part of the public interface of a module. But, when some_name is function, does that mean that all methods of some_name are meant for public usage?

If the answer is yes, IMO that could be problematic, but perhaps it makes sense at least as a default. I assume it could still be overridden by explicit documentation?

If the answer is no, it would be good to add an additional feature to be able to mark individual methods as public.

In any case this should be clarified in the docs.

[nsajko]

Actually, I think in any case it'd be great to have "marking individual methods as public" as a new feature.

[KristofferC]

It seems strange to me to have some methods public and some not in view of generic code. Can you really say that a function uses internals or not depending on what it is called with? It is often impossible to know in advance what types will end up getting passed to your function so how can you then ever say that you write generic code that does not use internals?

[nsajko]

Can you really say that a function uses internals or not depending on what it is called with?

Often different methods have a different number of arguments, so I'm thinking of something like this:

# internal method
f(a, b, c) = ...

# public method
f(a, b) = f(a, b, g(a, b))

In any case, I now agree with you that it'd be better if we had "function/constructor is public" implying "all its methods are public" as a rule. However would that be OK from a backwards-compatibility perspective? What if some registered package has some method that is meant as internal, you probably don't want to force the method public? Not sure how to check this.

[Tokazama]

I think this is a separate issue than the public/private API. It would be nice if we were able to freeze methods so they could be used publicly but not explicitly extended.

[barucden]

IIUC public marks symbols that belong to the public API. Hence any method of the given function?

[ToucheSir]

FWIW, the original PR and the GH + Discourse discussions it links to have very lengthy back-and-forths about whether the keyword should be function/symbol level or method level.

[Seelengrab]

Related #49973

[LilithHafner]

Public APIs are defined in terms of behavior, not methods.

The exact methods of a function are, unless explicitly stated otherwise, an implementation detail (see ?invoke for details) so it's typically not safe to count on the existence of specific methods, regardless of doccumented behavior of function publicity.

The documented behavior of a public function is part of the public API unless explicitly stated otherwise, so you should be able to depend on almost anything said in the docstring of a public function to remain stable across non-breaking releases.

If you document that foo(::Int) returns 5 and foo(:Float64) returns 6, and mark public foo, then both those behaviors are public, but there are lots of different sets of methods that could produce those behaviors.

The answer to the question

when some_name is public function, does that mean that all documented behavior of some_name is meant for public usage?

Is found here

Documented behavior of public symbols is part of the public API.

[StefanKarpinski]

I would add that if a function is public, you should really not add any methods to it that you don't want to be externally callable. In other words, if there's some helper functionality that is part of the implementation, even if you don't document it, the best practice should be to separate it into a separately named function. The best example of this may be a failure to do this in Base (my fault):

julia> methods(sort!)
# 16 methods for generic function "sort!" from Base:
  [1] sort!(r::AbstractUnitRange)
     @ range.jl:1398
  [2] sort!(x::SparseArrays.AbstractCompressedVector; kws...)
     @ SparseArrays ~/.julia/juliaup/julia-1.9.4+0.aarch64.apple.darwin14/share/julia/stdlib/v1.9/SparseArrays/src/sparsevector.jl:2129
  [3] sort!(v::AbstractVector{T}; alg, lt, by, rev, order, scratch) where T
     @ Base.Sort sort.jl:1367
  [4] sort!(v::AbstractVector, lo::Integer, hi::Integer, a::Base.Sort.QuickSortAlg, o::Base.Order.Ordering)
     @ Base.Sort sort.jl:2030
  [5] sort!(v::AbstractVector{T}, lo::Integer, hi::Integer, a::Base.Sort.MergeSortAlg, o::Base.Order.Ordering) where T
     @ Base.Sort sort.jl:2050
  [6] sort!(v::AbstractVector{T}, lo::Integer, hi::Integer, a::Base.Sort.MergeSortAlg, o::Base.Order.Ordering, t0::Vector{T}) where T
     @ Base.Sort sort.jl:2048
  [7] sort!(v::AbstractVector{T}, lo::Integer, hi::Integer, a::Base.Sort.MergeSortAlg, o::Base.Order.Ordering, t0::Union{Nothing, AbstractVector{T}}) where T
     @ Base.Sort sort.jl:2050
  [8] sort!(v::AbstractVector, lo::Integer, hi::Integer, a::PartialQuickSort, o::Base.Order.Ordering)
     @ Base.Sort sort.jl:2092
  [9] sort!(v::AbstractVector, a::Base.Sort.Algorithm, o::Base.Order.Ordering)
     @ Base.Sort sort.jl:2121
 [10] sort!(v::AbstractVector, lo::Integer, hi::Integer, a::Base.Sort.Algorithm, o::Base.Order.Ordering)
     @ Base.Sort sort.jl:2122
 [11] sort!(v::AbstractVector, lo::Integer, hi::Integer, a::Base.Sort.Algorithm, o::Base.Order.Ordering, scratch::Vector)
     @ Base.Sort sort.jl:2127
 [12] sort!(v::AbstractVector, lo::Integer, hi::Integer, a::Base.Sort.Algorithm, o::Base.Order.Ordering, ::Any)
     @ Base.Sort sort.jl:2126
 [13] sort!(A::AbstractArray{T}; dims, alg, lt, by, rev, order, scratch) where T
     @ Base.Sort sort.jl:1776
 [14] sort!(s::OrderedCollections.OrderedSet; kwargs...)
     @ OrderedCollections ~/.julia/packages/OrderedCollections/SInLM/src/dict_sorting.jl:26
 [15] sort!(d::OrderedCollections.OrderedDict; byvalue, args...)
     @ OrderedCollections ~/.julia/packages/OrderedCollections/SInLM/src/dict_sorting.jl:4
 [16] sort!(w::LibGit2.GitRevWalker; by, rev)
     @ LibGit2 ~/.julia/juliaup/julia-1.9.4+0.aarch64.apple.darwin14/share/julia/stdlib/v1.9/LibGit2/src/walker.jl:77

There are lots of effectively internal sort! methods that should really be split into a _sort! function instead. The ship may have sailed on that because this stuff has been exposed for a long time, but it exposes a lot of surface area that isn't really meant to be part of the public API.