Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documenting APIs with Examples: Lessons Learned...

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.

ASERG, DCC, UFMG

October 15, 2013
Tweet

More Decks by ASERG, DCC, UFMG

Other Decks in Research

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

     We widely know that “code examples are an essential element of API learning”, Robillard, DeLine, EMSE 2011 4
  3. 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
  4. 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
  5. 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
  6. Field Study  Data collected from Sep. 14th to Jan.

    18th  Google analytics service  Private logging service 15
  7. 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
  8. 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
  9. 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
  10. Lesson #1  Android API usage follows a power-law like

    distribution  We should not expect whole API coverage with examples 23
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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