$30 off During Our Annual Pro Sale. View Details »

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.

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

    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