A pet peeve of mine is when methods(f) shows more methods than is part of the documented API. Any chance the internal methods can be moved around a bit to prevent this?
In general, of course, you can rename internal methods to something like _f(...) or similar.
For an existing function like Markdown.parse, which is not technically public but is probably widely used nevertheless, there is a delicate question of how much backwards compatibility to maintain, but there is a reasonable argument that renaming internal, undocumented methods should be okay. Needs to be on a case-by-case basis, however.
5 Likes
Thanks for the explanation! Would candidate PRs largely look like renaming the internal methods, fixing calls to those methods as needed, and consulting package eval for its breaking status?
Right.
AFAIK only the name f and its behaviors could be public; the actual method table is part of the internal implementation, and documentation usually lumps several methods into one description. For example, I might document f(a::AbstractBar) for several methods specific to several AbstractBar subtypes; a f(a::AbstractBar) method may not even exist, and while I’m free to reorganize the existing methods, I cannot deviate from documented behavior, e.g. stop supporting some AbstractBar subtypes. If there are any methods that are not even indirectly documented, e.g. you call f(::Int) but don’t want users to, then yes those should be separated into different internal functions.
2 Likes