Should packages avoid using "private" API methods?


#1

I startet a small package called transform which does transformations on the current selections with a range of different functions (mostly from underscore.string).
Looking through the API docs, I did not find an existing convieniece method for this task (already dealing with the transaction and multiple selected buffers).
However, when looking up in the source code how the “native” (core) Edit > Text > Uppercase (and Lowercase) commands I noticed they’re using the Editor.replaceSelectedText() method.
I just now discovered the Editor.mutateSelectedText() method which also could be used, and all in all it is not to complicated to replicate replaceSelectedText; but my general question is:
how should package authors deal with private APIs in packages?
Should they be avoided completely?


#2

Since Atom hasn’t hit v1.0 yet, I think the entire API is considered to be in flux. Are some API calls “safer” than others? Sure … but figuring out which those are is probably going to be difficult.

Additionally, if you look at the “blame” view of the code for replaceSelectedText and mutateSelectedText:

https://github.com/atom/atom/blame/master/src/editor.coffee#L1041-L1060

You’ll notice that mutateSelectedText was originally written in 2012, but the documentation for it wasn’t written until just a couple months ago. It could just be that a year and a half ago (when replaceSelectedText was written), the Atom team wasn’t placing much of an emphasis on documentation … rather than a specific intention to make replaceSelectedText a private API call.