An Empirical Study on Evolution of API Documentation

  • Lin Shi
  • Hao Zhong
  • Tao Xie
  • Mingshu Li
Part of the Lecture Notes in Computer Science book series (LNCS, volume 6603)


With the evolution of an API library, its documentation also evolves. The evolution of API documentation is common knowledge for programmers and library developers, but not in a quantitative form. Without such quantitative knowledge, programmers may neglect important revisions of API documentation, and library developers may not effectively improve API documentation based on its revision histories. There is a strong need to conduct a quantitative study on API documentation evolution. However, as API documentation is large in size and revisions can be complicated, it is quite challenging to conduct such a study. In this paper, we present an analysis methodology to analyze the evolution of API documentation. Based on the methodology, we conduct a quantitative study on API documentation evolution of five widely used real-world libraries. The results reveal various valuable findings, and these findings allow programmers and library developers to better understand API documentation evolution.


Application Program Interface Behavioral Difference Code Clone Syntax Error Client Code 
These keywords were added by machine and not by the authors. This process is experimental and the keywords may be updated as the learning algorithm improves.


  1. 1.
    Bacchelli, A., Ambros, M.D., Lanza, M.: Are popular classes more defect prone? In: Rosenblum, D.S., Taentzer, G. (eds.) FASE 2010. LNCS, vol. 6013, pp. 59–73. Springer, Heidelberg (2010)CrossRefGoogle Scholar
  2. 2.
    Balaban, I., Tip, F., Fuhrer, R.: Refactoring support for class library migration. In: Proc. 20th OOPSLA, pp. 265–279 (2005)Google Scholar
  3. 3.
    Buse, R., Weimer, W.: Automatic documentation inference for exceptions. In: Proc. ISSTA, pp. 273–282 (2008)Google Scholar
  4. 4.
    Buse, R., Weimer, W.: Automatically documenting program changes. In: Proc. 26th ASE, pp. 33–42 (2010)Google Scholar
  5. 5.
    Dagenais, B., Robillard, M.: Recommending adaptive changes for framework evolution. In: Proc. 30th ICSE, pp. 481–490 (2009)Google Scholar
  6. 6.
    Dagenais, B., Robillard, M.P.: Creating and evolving developer documentation: Understanding the decisions of open source contributors. In: Proc. 18th ESEC/FSE, pp. 127–136 (2010)Google Scholar
  7. 7.
    Dekel, U., Herbsleb, J.D.: Improving API documentation usability with knowledge pushing. In: Proc. 31st ICSE, pp. 320–330 (2009)Google Scholar
  8. 8.
    Dig, D., Johnson, R.: How do APIs evolve? a story of refactoring. Journal of software maintenance and evolution: Research and Practice 18(2), 83–107 (2006)CrossRefGoogle Scholar
  9. 9.
    Geiger, R., Fluri, B., Gall, H., Pinzger, M.: Relation of code clones and change couplings. In: Baresi, L., Heckel, R. (eds.) FASE 2006. LNCS, vol. 3922, pp. 411–425. Springer, Heidelberg (2006)CrossRefGoogle Scholar
  10. 10.
    Henkel, J., Diwan, A.: CatchUp!: capturing and replaying refactorings to support API evolution. In: Proc. 27th ICSE, pp. 274–283 (2005)Google Scholar
  11. 11.
    Horie, M., Chiba, S.: Tool support for crosscutting concerns of API documentation. In: Proc. 8th AOSD, pp. 97–108 (2010)Google Scholar
  12. 12.
    Kim, J., Lee, S., Hwang, S., Kim, S.: Adding examples into Java documents. In: Proc. 24th ASE, pp. 540–544 (2009)Google Scholar
  13. 13.
    Kof, L.: Scenarios: Identifying missing objects and actions by means of computational linguistics. In: Proc. 15th RE, pp. 121–130 (2007)Google Scholar
  14. 14.
    Mariani, L., Pastore, F., Pezze, M.: A toolset for automated failure analysis. In: Proc. 31st ICSE, pp. 563–566 (2009)Google Scholar
  15. 15.
    Mens, T., Tourwe, T.: A survey of software refactoring. IEEE Transactions on software engineering 30(2), 126–139 (2004)CrossRefGoogle Scholar
  16. 16.
    Novick, D.G., Ward, K.: Why don’t people read the manual? In: Proc. 24th SIGDOC, pp. 11–18 (2006)Google Scholar
  17. 17.
    Padioleau, Y., Tan, L., Zhou, Y.: Listening to programmers Taxonomies and characteristics of comments in operating system code. In: Proc. 31st ICSE, pp. 331–341 (2009)Google Scholar
  18. 18.
    Robillard, M.P., DeLine, R.: A field study of API learning obstacles. Empirical Software Engineering (to appear, 2011)Google Scholar
  19. 19.
    Ruffell, F., Selby, J.: The pervasiveness of global data in evolving software systems. In: Baresi, L., Heckel, R. (eds.) FASE 2006. LNCS, vol. 3922, pp. 396–410. Springer, Heidelberg (2006)CrossRefGoogle Scholar
  20. 20.
    Sridhara, G., Hill, E., Muppaneni, D., Pollock, L.L., Vijay-Shanker, K.: Towards automatically generating summary comments for Java methods. In: Proc. 25th ASE, pp. 43–52 (2010)Google Scholar
  21. 21.
    Tan, L., Yuan, D., Krishna, G., Zhou, Y.: iComment: Bugs or bad comments. In: Proc. 21st SOSP, pp. 145–158 (2007)Google Scholar
  22. 22.
    Tan, L., Zhou, Y., Padioleau, Y.: aComment: Mining annotations from comments and code to detect interrupt-related concurrency bugs. In: Proc. 33rd ICSE (to appear, 2011)Google Scholar
  23. 23.
    Würsch, M., Ghezzi, G., Reif, G., Gall, H.C.: Supporting developers with natural language queries. In: Proc. 32nd ICSE, pp. 165–174 (2010)Google Scholar
  24. 24.
    Xing, Z., Stroulia, E.: API-evolution support with Diff-CatchUp. IEEE Transactions on Software Engineering 33(12), 818–836 (2007)CrossRefGoogle Scholar
  25. 25.
    Zhong, H., Thummalapenta, S., Xie, T., Zhang, L., Wang, Q.: Mining API mapping for language migration. In: Proc. 32nd ICSE, pp. 195–204 (2010)Google Scholar
  26. 26.
    Zhong, H., Zhang, L., Xie, T., Mei, H.: Inferring resource specifications from natural language API documentation. In: Proc. 24th ASE, pp. 307–318 (2009)Google Scholar

Copyright information

© Springer-Verlag Berlin Heidelberg 2011

Authors and Affiliations

  • Lin Shi
    • 1
  • Hao Zhong
    • 1
  • Tao Xie
    • 3
  • Mingshu Li
    • 1
    • 2
  1. 1.Laboratory for Internet Software Technologies, Institute of SoftwareChinese Academy of SciencesBeijingChina
  2. 2.Key Laboratory for Computer ScienceChinese Academy of SciencesBeijingChina
  3. 3.Department of Computer ScienceNorth Carolina State UniversityUSA

Personalised recommendations