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
   

   View Slide

2. Motivation
    APIs are increasingly complex and hard to learn
   2
   

   View Slide

3. Motivation
    APIs are increasingly complex and hard to learn
   3
   

   View Slide

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
   

   View Slide

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
   

   View Slide

6. APIMiner
    APIMiner = JavaDocs + Examples Button
   6
   

   View Slide

7. Architecture
   7
   

   View Slide

8. Architecture
   8
   

   View Slide

9. Architecture
   9
   

   View Slide

10. Architecture
    10
    

    View Slide

11. Android APIMiner
    

    View Slide

12. Android APIMiner
     103 open-source apps
     2,494 methods (18%)
    12
    

    View Slide

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
    

    View Slide

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
    

    View Slide

15. Field Study
     Data collected from Sep. 14th to Jan. 18th
     Google analytics service
     Private logging service
    15
    

    View Slide

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
    

    View Slide

17. Visits in the Last Week
    17
    

    View Slide

18. Demographics
    Visits from 130 countries
    18
    

    View Slide

19. Number of Examples
    2,157 examples
    (1 example every 10 visits)
    19
    

    View Slide

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
    

    View Slide

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
    

    View Slide

22. Lessons Learned
    22
    

    View Slide

23. Lesson #1
     Android API usage follows a power-law like distribution
     We should not expect whole API coverage with examples
    23
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

28. Limitation
     Cold-start problem
     Examples only available after the API has been used
    28
    

    View Slide

29. Final Remarks
    29
    

    View Slide

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
    

    View Slide

31. Ongoing work: APIMiner 2.0
    31
     Association rules:
     Examples for methods frequently called together
    

    View Slide

32. Ongoing work: IDE version
    32
    

    View Slide

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
    

    View Slide

34. Thanks!
    apiminer.org
    34
    WCRE, Koblenz, Germany, October 2013
    

    View Slide