Document how public API is defined (depends on scoped export)

[LilithHafner]

This PR is an extension of JuliaLang/julia#50105 and should be merged or closed simultaneously.

The key sentence is

Unless you note otherwise, the public API of your package is defined as all the behavior you
describe about exported symbols

And the reason this definition is viable is that scoped exports allow you to export symbols without the namespace implications.

[KristofferC]

In general I think things like this are better off in the Julia manual. In some sense, Pkg is "just" a package manager and someone could in theory write another better one. And we should IMO then try to keep the documentation to package management and less about general julia package information. I realize that things are pretty muddy now (for example the extension documentation is in Pkg, which it probably shouldn't be), but I think it is something to strive for.

[c42f]

Agree @KristofferC that this stuff would be better in the Julia manual. The issue as I see it, is that the manual has no place for tutorial-style docs.

So how about we just merge this here for now alongside the extensions stuff? Because it's strictly better to have this documented somewhere rather than sitting in a stale PR :)

[KristofferC]

So how about we just merge this here for now alongside the extensions stuff? Because it's strictly better to have this documented somewhere rather than sitting in a stale PR :)

I mean, we don't even have public in Base so it feels kind of premature to merge the doc change before the feature itself even exists.

[LilithHafner]

I think "merge this here for now" means at the same time as the public keyword merges in Base