Programmers are famous for not doing a great job of documenting the interfaces of their projects (whether these are libraries with APIs, protocols, programming languages, or whatever). The problems that this causes for people who are trying to use your work are well known, but it's recently struck me that open source projects in particular have an additional issue.

In the absence of documentation, people working with open source projects can always read the source to find out how to do something, to discover the interface that the project written down yet. But when you do so, you're left with a question: is what you've found something that you should actually be using?

There's at least three possibilities. First, you could have found the right answer, the correct interface to use for what you want to do, and it just hasn't been documented yet. Second, you could have found an unsupported and unstable internal interface or an implementation detail. Third, you could have found an experimental interface that the project authors haven't finalized yet (and thus haven't documented).

(I'm going to assume here that the name of the interface and other details in the code give an outsider no obvious clues. Remember that the people searching through the guts of your library probably don't have deep experience with the code base and your conventions.)

The quality of documentation matters here. The more clearly patchy and incomplete the documentation, the less guidance it can give you about which possibility you've hit; conversely, the more complete the documentation the more you can infer something from things not being documented. How the documentation is created also matters; people can infer one thing from entirely hand-written documentation and another from documentation that is at least partly automatically extracted from source code.

Of course, an explicit mention of this issue in your documentation helps to some degree, but make sure that it's believable and useful. Saying 'anything not mentioned here is internal and unsupported' is pretty pointless if your documentation is clearly incomplete, because you give people the choice of either ignoring your warning or ignoring your project entirely. (You lose either way.)

(I don't think that this issue is completely avoided in systems where you have to explicitly mark things to be publicly visible, just reduced somewhat. Of course you could always modify your build system so that basic interface documentation is automatically extracted and only things with such documentation are marked as publicly visible.)