Developing software involves (re-)using libraries, frameworks, SDKs, etc. which we call them, collectively, APIs. Developers need to learn how to use different APIs, in order to build software systems or make changes to them. Therefore, using and learning APIs is an everyday activity for developers. Like everything that we use on a daily basis, APIs must be designed in a way that facilitates their usage and hinders users from making too many mistakes.
If an API was already published and is in use, it is very difficult to change it, because it will break all the code that depends on that API. Therefore, a less usable API with design flaws can be in use for a long time, making developers unhappy by making their lives miserable. In this case, additional information about the API can be helpful. The API documentation and API usage examples are two sources of information about the API that can alleviate the problem of using and/or learning a (new) API.
We are currently investigating the effect of using API's unit tests as a source of examples that can be used in learning an API. Unit tests are considered as the live documentation of the unit under test, and this gives us the idea that they could provide good API usage examples. Furthermore, we want to determine what the characteristics of good examples are, and how they can be retrieved from unit tests. We also want to determine how different sources of information (i.e., examples and documentation) can be represented to enhance the learnability of APIs.