Document what public API means #35715
Conversation
|
Sometimes the manual mentions "internal" methods (e.g. methods starting with underscore in the chapter on methods). Maybe one could clarify that apparently "non-internal" does not mean "public". |
|
👍 to adding this. I'm sure @StefanKarpinski will want to weigh in. |
|
This feels a little too restrictive. People can rely on internal code if they want to, but they just need to be aware that we may change it and break their code. If they're ok with that, then carry on. But if they find it useful then someone else may as well, so it would be helpful if they would open an issue to figure out a way to expose the functionality in some official way. |
|
I'd say "internal" is exactly the complement of "public".
If so, could you then change the corresponding wording about "internal methods"
in the manual section about methods?
Starting with `_` is not really anything to do with public API or not.
It is assumed to be an internal marker in a lot of other programming languages
(and in some places of Julia's manual), so some clarification should be in place.
For example,
[`OnlineStatsBase._fit!`](https://github.com/joshday/OnlineStatsBase.jl) is a
public API. As you can see, these function names tend to be used as "mostly
overload only" API; but they are still public.
So looking from the other side: exported functions that are not documented are
not considered public? It will take a time for me to get used to that.
|
I'm not sure what is inconsistent with the part you linked. If you think you have a better wording in that part, the best way is to open an PR. It's touching a different part of the documentation so it can be discussed independently.
Yes, it is "assumed" to be; but not always true. In a lot of programming languages it is used in public interface when it's doing something tricky (an example in Python; an example in C).
You have to declare public API to use SemVer. That's the very first thing mentioned in SemVer spec. Writing documentation is more or less the only way to declare public API in Julia at the moment (it'd be nice to improve this, of course). Obviously, I'm only describing an ideal case. In practice, you may be able to rely on kindness of the library authors to avoid abrupt change in not-strictly-stable API. |
|
`export` alone does not mean anything because it doesn't tell you what
interface the exported names satisfy.
Thank you, that makes sense.
|
I don't think this is entirely true; anything exported should be considered public, and it's considered a bug for an exported identifier not to have documentation. But even if an exported name didn't have documentation, it would at least need to remain exported and do something like what it did before to avoid breaking code. |
|
Yes, I agree that's the best action once undocumented |
|
Fun fact: merging this would close the least-recently-updated open issue (#7561). |
|
Bump. This would be nice to get merged and feels like we are close. |
|
I can't see any reason not to have merged this. |
Provides some guidelines, in addition to those added recently by JuliaLang#40533 to the style-guide, per JuliaLang#7561.
Provides some guidelines, in addition to those added recently by JuliaLang#40533 to the style-guide, per JuliaLang#7561.
Provides some guidelines, in addition to those added recently by JuliaLang#40533 to the style-guide, per JuliaLang#7561.
I think there is confusion in Julia community for what it means to be a public API. I think clarifying it in documentation makes sense.
Closes #7561.