More Web Proxy on the site http://driver.im/

article

What should developers be aware of? An empirical study on the directives of API documentation

Authors:

Martin Monperrus,

Michael Eichberg,

Mira MeziniAuthors Info & Claims

Empirical Software Engineering, Volume 17, Issue 6

Pages 703 - 737

https://doi.org/10.1007/s10664-011-9186-4

Published: 01 December 2012 Publication History

Abstract

Application Programming Interfaces (API) are exposed to developers in order to reuse software libraries. API directives are natural-language statements in API documentation that make developers aware of constraints and guidelines related to the usage of an API. This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries. Its main contribution is to propose and extensively discuss a taxonomy of 23 kinds of API directives.

References

[1]

Alexander C, Ishikawa S, Silverstein M (1977) A pattern language: towns, buildings, construction. Oxford University Press.

[2]

Arnout K, Meyer B (2003) Uncovering hidden contracts: the .net example. Comput 36:48-55.

Digital Library

[3]

Beckman NE, Kim D, Aldrich J (2011) An empirical study of object protocols in the wild. In: Proceedings of the European conference on object-oriented programming. Springer.

[4]

Bierhoff K, Beckman NE, Aldrich J (2009) Practical api protocol checking with access permissions. In: Proceedings of the 23rd European conference on object-oriented programming, Genoa. Springer, Berlin, Heidelberg, pp 195-219.

[5]

Bloch J (2008) Effective java, 2nd edn. Addisson-Wesley.

[6]

Bokowski B (2008) Java API design. In: Tutorial at the EclipseCon conference.

[7]

Bokowski B, Arthorne J, des Rivières J (2006) Designing eclipse APIs. In: Tutorial at the EclipseCon conference.

[8]

Bradner S (1997) Key words for use in rfcs to indicate requirement levels. Technical report, IETF.

[9]

Brooks F (1995) The mythical man-month: essays on software engineering. Addison-Wesley.

[10]

Bruch M, Mezini M, Monperrus M (2010) Mining subclassing directives to improve framework reuse. In: Proceedings of the 7th IEEE working conference on mining software repositories. IEEE.

[11]

Clarke S (2004) Measuring API usability. Dr Dobb's J 29(5):1-5.

[12]

Cockburn A (2000) Writing effective use cases, 1st edn. Addison-Wesley Longman Publishing Co, Inc.

[13]

Dekel U (2009) Increasing awareness of delocalized information to facilitate API usage. PhD thesis, Carnegie Mellon University.

[14]

Dekel U, Herbsleb JD (2009) Improving API documentation usability with knowledge pushing. In: Proceedings of the 31st international conference on software engineering. IEEE Computer Society, pp 320-330.

Digital Library

[15]

Easterbrook S, Singer J, Storey M-A, Damian D (2007) Selecting empirical methods for software engineering research.

[16]

Ellis B, Stylos J, Myers B (2007) The factory pattern in api design: a usability evaluation. In: Proceedings of the 29th International Conference on Software Engineering, ICSE '07. IEEE Computer Society, pp 302-312.

[17]

Gamma E, Helm R, Johnson RE, Vlissides J (1995) Design patterns: elements of reusable objectoriented software. Addison-Wesley.

[18]

Hovemeyer D, Spacco J, Pugh W (2005) Evaluating and tuning a static analysis to find null pointer bugs. In: Proceedings of the 6th ACM SIGPLAN-SIGSOFT workshop on program analysis for software tools and engineering, PASTE '05. ACM, New York, NY, USA, pp 13-19.

[19]

Jiang ZM, Hassan AE (2006) Examining the evolution of code comments in postgresql. In: Proceedings of the 2006 international workshop on mining software repositories. ACM, pp 179-180.

[20]

Kramer D (1999) API documentation from source code comments: a case study of javadoc. In: Proceedings of the 17th international conference on computer documentation. ACM, pp 147-153.

[21]

Monperrus M, Eichberg M, Tekes E, Mezini M (2011) Companion web page for "What should developers be aware of? An empirical study on the directives of API documentation". http://www.monperrus.net/martin/api-directives. Last accessed: 12 Oct 2011.

[22]

Nanda MG, Sinha S (2009) Accurate interprocedural null-dereference analysis for java. In: Proceedings of the 31st international conference on software engineering. IEEE Computer Society, pp 133-143.

Digital Library

[23]

Padioleau Y, Tan L, Zhou Y (2009) Listening to programmers? Taxonomies and characteristics of comments in operating system code. In: Proceedings of the 31st international conference on software engineering. IEEE, pp 331-341.

Digital Library

[24]

Parnin C, Treude C (2011) Measuring API documentation on the Web. In: Proceeding of the 2nd international workshop on Web 2.0 for software engineering, Web2SE '11. ACM, pp 25-30.

[25]

Robillard MP (2009) What makes APIs hard to learn? Answers from developers. IEEE Softw 26(6):27-34.

Digital Library

[26]

Shi L, Zhong H, Xie T, Li M (2011) An empirical study on evolution of api documentation. In: Proceedings of the 14th international conference on Fundamental Approaches to Software Engineering, FASE'11/ETAPS'11. Springer, pp 416-431.

[27]

Singh R, Mangat NS (1996) Elements of survey sampling. Springer.

[28]

Smith KA, Kramer D (2003) Requirements for writing java API specifications. Technical report, Sun.

[29]

Storey MA, Ryall J, Bull RI, Myers D, Singer J (2008) TODO or to bug. In: Proceedings of the ACM/IEEE 30th international conference on software engineering. IEEE, pp 251-260.

[30]

Stylos J (2009) Making APIs more usable with improved API designs, documentation and tools. PhD thesis, Carnegie Mellon University.

[31]

Stylos J, Myers BA (2008) The implications of method placement on API learnability. In: Proceedings of the 16th ACM SIGSOFT international symposium on foundations of software engineering, SIGSOFT '08/FSE-16. ACM, New York, NY, USA, pp 105-112.

[32]

Stylos J, Graf B, Busse DK, Ziegler C, Ehret R, Karstens J (2008) A case study of api redesign for improved usability. In: IEEE symposium on visual languages and human-centric computing, pp 189-192.

[33]

Stylos J, Faulring A, Yang Z, Myers BA (2009a) Improving API documentation using API usage information. In: Proceedings of the IEEE symposium on Visual Languages and Human-Centric Computing (VL/HCC'09).

[34]

Stylos J, Myers BA, Yang Z (2009b) Jadeite: improving API documentation using usage information. In: Proceedings of the 27th international conference on human factors in computing systems. ACM, pp 4429-4434.

[35]

Tan L, Yuan D, Krishna G, Zhou Y (2007) icomment: bugs or bad comments. In: Proceedings of the symposium on operating systems principles.

[36]

Thummalapenta S, Xie T (2008) Spotweb: detecting framework hotspots and coldspots via mining open source code on the Web. In: Proceedings of the international conference on automated software engineering, pp 327-336.

[37]

Tulach J (2008) Practical API design: confessions of a java framework architect. Apress.

[38]

Watson RB (2009) Improving software API usability through text analysis: a case study. In: Proceedings of the professional communication conference, pp 1-7.

[39]

Ying ATT, Wright JL, Abrams S (2005) Source code that talks: an exploration of Eclipse task comments and their implication to repositorymining. In: Proceedings of mining software repositories. ACM, pp 1-5.

[40]

Zhong H, Zhang L, Xie T, Mei H (2009) Inferring resource specifications from natural language API documentation. In: Proceedings of the international conference on automated software engineering. IEEE Computer Society, pp 307-318.

Cited By

Galappaththi ANadi STreude C(2024)An Empirical Study of API Misuses of Data-Centric LibrariesProceedings of the 18th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement10.1145/3674805.3686685(245-256)Online publication date: 24-Oct-2024
https://dl.acm.org/doi/10.1145/3674805.3686685
Ma YTian WGao XSun HLi LChristakis MPradel M(2024)API Misuse Detection via Probabilistic Graphical ModelProceedings of the 33rd ACM SIGSOFT International Symposium on Software Testing and Analysis10.1145/3650212.3652112(88-99)Online publication date: 11-Sep-2024
https://dl.acm.org/doi/10.1145/3650212.3652112
Latappy CDegueule TFalleri JRobbes RBlanc XTeyton CBaysal OLinares-Vasquez MMoran KSteinmacher I(2024)What the Fix? A Study of ASATs Rule DocumentationProceedings of the 32nd IEEE/ACM International Conference on Program Comprehension10.1145/3643916.3644404(246-257)Online publication date: 15-Apr-2024
https://dl.acm.org/doi/10.1145/3643916.3644404
Show More Cited By

Recommendations

How developers use API documentation: an observation study

Application Programming Interfaces (APIs) play a crucial role in modern software engineering. However, learning to use a new API often is a challenge for developers. In order to support the learning process effectively, we need to understand how ...
Automatic Summarization of API Artifacts from Informal Documentation
How Do Developers React to RESTful API Evolution?
Service-Oriented Computing
Abstract
With the rapid adoption of REpresentational State Transfer (REST), more software organizations expose their applications as RESTful web APIs and client code developers integrate RESTful APIs into their applications. When web APIs evolve, the ...

Comments

Please enable JavaScript to view thecomments powered by Disqus.

Information & Contributors

Information

Published In

cover image Empirical Software Engineering

Empirical Software Engineering Volume 17, Issue 6

December 2012

148 pages

ISSN:1382-3256

Issue’s Table of Contents

Copyright © Copyright © 2012 Springer Science+Business Media, LLC.

Publisher

Kluwer Academic Publishers

United States

Publication History

Published: 01 December 2012

Qualifiers

Article

Contributors

Other Metrics

View Article Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

29
Total Citations
View Citations
0
Total Downloads

Downloads (Last 12 months)0
Downloads (Last 6 weeks)0

Reflects downloads up to 14 Jan 2025

Other Metrics

View Author Metrics

Citations

Cited By

Galappaththi ANadi STreude C(2024)An Empirical Study of API Misuses of Data-Centric LibrariesProceedings of the 18th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement10.1145/3674805.3686685(245-256)Online publication date: 24-Oct-2024
https://dl.acm.org/doi/10.1145/3674805.3686685
Ma YTian WGao XSun HLi LChristakis MPradel M(2024)API Misuse Detection via Probabilistic Graphical ModelProceedings of the 33rd ACM SIGSOFT International Symposium on Software Testing and Analysis10.1145/3650212.3652112(88-99)Online publication date: 11-Sep-2024
https://dl.acm.org/doi/10.1145/3650212.3652112
Latappy CDegueule TFalleri JRobbes RBlanc XTeyton CBaysal OLinares-Vasquez MMoran KSteinmacher I(2024)What the Fix? A Study of ASATs Rule DocumentationProceedings of the 32nd IEEE/ACM International Conference on Program Comprehension10.1145/3643916.3644404(246-257)Online publication date: 15-Apr-2024
https://dl.acm.org/doi/10.1145/3643916.3644404
Schlichtig MRoychoudhury APaiva AAbreu RStorey M(2024)Building a Framework to Improve the User Experience of Static Analysis ToolsProceedings of the 2024 IEEE/ACM 46th International Conference on Software Engineering: Companion Proceedings10.1145/3639478.3639813(165-169)Online publication date: 14-Apr-2024
https://dl.acm.org/doi/10.1145/3639478.3639813
Ren XYe XLin YXing ZLi SLyu MChandra SBlincoe KTonella P(2023)API-Knowledge Aware Search-Based Software Testing: Where, What, and HowProceedings of the 31st ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering10.1145/3611643.3616269(1320-1332)Online publication date: 30-Nov-2023
https://dl.acm.org/doi/10.1145/3611643.3616269
Rani PBlasi AStulova NPanichella SGorla ANierstrasz O(2023)A decade of code comment quality assessmentJournal of Systems and Software10.1016/j.jss.2022.111515195:COnline publication date: 1-Jan-2023
https://dl.acm.org/doi/10.1016/j.jss.2022.111515
Vidoni MCodabux Z(2023)Towards a taxonomy of Roxygen documentation in R packagesEmpirical Software Engineering10.1007/s10664-023-10345-428:4Online publication date: 15-Jul-2023
https://dl.acm.org/doi/10.1007/s10664-023-10345-4
Yan AZhong HSong DJia L(2023)How do programmers fix bugs as workarounds? An empirical study on Apache projectsEmpirical Software Engineering10.1007/s10664-023-10318-728:4Online publication date: 28-Jun-2023
https://dl.acm.org/doi/10.1007/s10664-023-10318-7
Zhong HWang X(2023)An empirical study on API usages from code search engine and local libraryEmpirical Software Engineering10.1007/s10664-023-10304-z28:3Online publication date: 13-Apr-2023
https://dl.acm.org/doi/10.1007/s10664-023-10304-z
Zhu CLiu YWu XLi Y(2022)Identifying Solidity Smart Contract API Documentation ErrorsProceedings of the 37th IEEE/ACM International Conference on Automated Software Engineering10.1145/3551349.3556963(1-13)Online publication date: 10-Oct-2022
https://dl.acm.org/doi/10.1145/3551349.3556963
Show More Cited By

View Options

View options

Media

Figures

Other

Tables

View Issue’s Table of Contents