Define public API

[markandrus]

Thank you all for this valuable resource. I was catching up on current practices with respect to "private" properties in JavaScript when I came upon the discussion in #490. It seems to me that the definition of public API used by this style guide is stricter than what SemVer describes. For example, the guide currently states that

Although a leading underscore is a common convention to mean “private”, in fact, these properties are fully public, and as such, are part of your public API contract.

So, as far as this guide is concerned, anything which is accessible in a JavaScript library constitutes its public API. On the other hand, SemVer describes public API differently:

1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

I take this to mean that, as a library author, I am free to explicitly include and exclude properties from my public API, regardless of whether or not they are accessible in my JavaScript library.

So I propose that this guide define public API for itself and explain why it adheres to the definition that it does. I think this would inform developers evaluating the pros and cons of whether or not to adopt or reject a private convention in their projects.

[ljharb]

Public API is everything reachable and accessible at runtime, full stop.

semver.org's description is more pragmatic out of necessity, because the value of semver exists no matter how public API is defined. The reality is that if you cause any user anywhere to break, not matter how dumb the thing they're doing is, you made a breaking change; it's your fault; and you have a moral and ethical obligation to fix it.

Totally separately - "private" to most people has connotations that it is unreachable - not just that "it'd be really swell if you didn't interact with it". Our guide's stance on privacy is unrelated to the definition of "public API", because the word "private" carries connotations that transcend any given specification's definition.

[markandrus]

Public API is everything reachable and accessible at runtime, full stop.

I think it would make sense to expand upon this position in some form in the guide. "Public API" is currently only mentioned in 22.4, but I think it could also inform future work on the Comments section. I know some projects prescribe that all exported API members should be documented, but I'm not sure the guide's current position.

[ljharb]

Documentation is a good thing, but I don't think it's always necessary to document all of the public API.

Adding a section to the guide about public API seems like a good idea.