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

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.

13beaa3b7239eca3319d54c6a9f3a85a?s=128

ASERG, DCC, UFMG

October 15, 2013
Tweet

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