Documenting APIs with Examples: Lessons Learned with the APIMiner Platform (WCRE 2013)

Software development increasingly relies on Application Programming Interfaces (APIs) to increase productivity. However, learning how to use new APIs in many cases is a nontrivial task given their ever-increasing complexity. To help developers during the API learning process, we describe in this paper a platform—called APIMiner—that instruments the standard Java-based API documentation format with concrete examples of usage. The examples are extracted from a private source code repository—composed by real systems—and summarized using a static slicing algorithm. We also describe a particular instantiation of our platform for the Android API. To evaluate the proposed solution, we performed a field study, when professional Android developers used the platform by four months.

Transcript

1. Documenting APIs with Examples: Lessons Learned with the APIMiner Platform João Eduardo Montandon, Hudson Borges, Daniel Felix, Marco Tulio Valente 1 WCRE, Koblenz, Germany, October 2013
2. Motivation  APIs are increasingly complex and hard to learn 2
3. Motivation  APIs are increasingly complex and hard to learn 3
4. Motivation  APIs are increasingly complex and hard to learn  We widely know that “code examples are an essential element of API learning”, Robillard, DeLine, EMSE 2011 4
5. Motivation  APIs are increasingly complex and hard to learn  We widely know that “code examples are an essential element of API learning”, Robillard, DeLine, EMSE 2011  JavaDocs usually have very few examples 5
6. APIMiner  APIMiner = JavaDocs + Examples Button 6
7. Architecture 7
8. Architecture 8
9. Architecture 9
10. Architecture 10
11. Android APIMiner
12. Android APIMiner  103 open-source apps  2,494 methods (18%) 12
13. Android APIMiner  103 open-source apps  2,494 methods (18%)  79,732 source code examples  75% of the examples have less than 10 LOC 13
14. Android APIMiner  103 open-source apps  2,494 methods (18%)  79,732 source code examples  75% of the examples have less than 10 LOC  Top 10 packages: 72,900 (91%)  Top 10 classes: 43,288 (54%)  Top 10 methods: 15,293 (19%) 14
15. Field Study  Data collected from Sep. 14th to Jan. 18th  Google analytics service  Private logging service 15
16. Number of Visits Traffic Origin # Visits % Visits Organic search 14,412 72 Referral traffic 3,393 17 Direct access 2,233 11 Total 20,038 100 Reddit 16
17. Visits in the Last Week 17
18. Demographics Visits from 130 countries 18
19. Number of Examples 2,157 examples (1 example every 10 visits) 19
20. Top-10 Search Queries Keyword # Queries speechrecognizer wait timeout 53 apiminer 30 datepicker.keep_screen_on 16 eglquerysurface egl_width android resize 15 listpopupwindow example android 15 android.net.rtp example 14 gridlayoutanimationcontroller example 13 android notificationcompat example 12 notificationcompat.builder example 12 fragmentactivity example 11 Total 191 20
21. Top-10 Search Queries Keyword # Queries speechrecognizer wait timeout 53 apiminer 30 datepicker.keep_screen_on 16 eglquerysurface egl_width android resize 15 listpopupwindow example android 15 android.net.rtp example 14 gridlayoutanimationcontroller example 13 android notificationcompat example 12 notificationcompat.builder example 12 fragmentactivity example 11 Total 191 21
22. Lessons Learned 22
23. Lesson #1  Android API usage follows a power-law like distribution  We should not expect whole API coverage with examples 23
24. Lesson #2  Developers care about source code examples  1 example every 10 visits  6 out of 10 top queries have the word example  Time-consuming to provide examples for ~2500 methods  Examples should be extracted automatically 24
25. Lesson #3  There is no correlation between:  Methods with more source code examples  Methods with more examples requests (by users)  Spearman’s coefficient = -0.04 25
26. Lesson #4  APIMiner is also useful to API developers  Dashboard of API usage  Methods effectively used by client code  Methods with more examples requests 26
27. Lesson #4  APIMiner is also useful to API developers  Dashboard of API usage  Methods effectively used by client code  Methods with more examples requests  Useful to improve the original JavaDoc  Human-crafted examples  API redesign: deprecation, simple interfaces etc 27
28. Limitation  Cold-start problem  Examples only available after the API has been used 28
29. Final Remarks 29
30. Central Objective  APIMiner is not the first system to instrument APIs  ExoaDocs, APIExample etc  Central goal:  Testbed for evaluating and implementing such systems  Goal #1: baseline implementation  Classical summarization (slicing)  Scalable and robust; seamless JavaDoc integration  Goal # 2: dataset  Relevant API and users (Android, ~400 visits/day)  Real dataset of API usage (1 year) 30
31. Ongoing work: APIMiner 2.0 31  Association rules:  Examples for methods frequently called together
32. Ongoing work: IDE version 32
33. Next Work  Take advantage of our implementation and base of users  Extending APIMiner with new algorithms:  Summarization, ranking, clustering etc  Sequencing  Evaluation:  User studies  Comparison with other systems (Stackoverflow)  New APIs:  Java API etc 33
34. Thanks! apiminer.org 34 WCRE, Koblenz, Germany, October 2013