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.
This is a preview of subscription content, log in via an institution to check access.
Access this article Subscribe and saveSpringer+ Basic
€34.99 /Month
Price includes VAT (Germany)
Instant access to the full article PDF.
Similar content being viewed by others Explore related subjectsDiscover the latest articles and news from researchers in related subjects, suggested using machine learning. NotesEclipse is an extensible development environment primarily targeted for Java.
See http://www.oracle.com/technetwork/java/javase/index.html.
See http://msdn.microsoft.com/en-us/library/d06h2x6e(v=VS.100).aspx.
This version of JDK is available at http://download.java.net/jdk6/6u21/promoted/b05/.
$ cvs -d :pserver:anonymous@dev.eclipse.org/cvsroot/eclipse/ co -D “15 Oct 2009” org.eclipse.jface
To create and query the index, we used Lucene, see http://lucene.apache.net.
in Commons Collections’ CollatingIterator.addIterator(iterator)
in JDK’s RuntimePermission.RuntimePermission(name, actions)
in JFace’s IInformationControlExtension5.getInformationPresenterControlCreator()
in JDK’s Math.cos(a)
in JFace’s Dialog.getParent()
in JDK’s JobAttributes.getPageRanges()
in JDK’s RMIClassLoaderSpi.loadClass(codebase, name, defaultLoader)
in JFace’s PopupDialog.createDialogArea(parent)
in JDK’s Logger.setParent(parent)
in Commons Collections’ AbstractOrderedMapDecorator.AbstractOrderedMapDecorator()
in JFace’s ListEditor.getShell()
in JDK’s ActivationDesc.ActivationDesc(groupID, className, location, data, restart)
in JDK’s PolicySpi
in JDK’s LSParserFilter
in JDK’s Map.Entry.getKey()
in JDK’s DatabaseMetaData.getColumnPrivileges(catalog, schema, table, columnNamePattern)
in JFace’s ContentProposalAdapter.setAutoActivationCharacters(autoActivationCharacters)
Runtime.load(filename): “The filename argument must be a complete path name, (for example Runtime.getRuntime().load(“/home/avh/lib/libX11.so‘’);)”.
in JDK’s HttpCookie.HttpCookie(name, value)
in JDK’s ManagementPermission.ManagementPermission(name, actions). Although this may seem to be a bad design, we include it here since examples like this do appear in the APIs we studied.
in JDK’s Statement.execute(sql, autoGeneratedKeys)
in JDK’s ServerSocket.ServerSocket(port, backlog, bindAddr)
in JDK’s CallableStatement.registerOutParameter(parameterIndex, sqlType, scale)
in JDK’s DateFormat.format(obj, toAppendTo, fieldPosition)
in JDK’s CertPathValidator.validate(certPath, params)
in JDK’s MarshalledObject.MarshalledObject(obj)
in JDK’s KeyStore.setKeyEntry(alias, key, password, chain)
in JDK’s CallableStatement.setNClob(parameterName, reader, length)
in AlgorithmParameters.getInstance(algorithm)
in JDK’s File.renameTo(dest)
in JDK’s PortableRemoteObject.toStub(obj)
in JDK’s Runtime.addShutdownHook(hook)
in JDK’s ActivationGroup.inactiveObject(id)
in JFace’s LabelProvider
in Apache Commons Collections’ AbstractLinkedList.isEqualValue(value1, value2)
in JDK’s ThreadLocal.initialValue()
in JFace’s StyledCellLabelProvider
in Apache Commons Collections’ AbstractLinkedList
in JDK’s BigDecimal.setScale(newScale, roundingMode)
in JFace’s Dialog.createDialogArea(parent
in Apache Commons Collections’ Bag.remove(object)
in JFace’s StringFieldEditor.doFillIntoGrid(parent, numColumns)
in JDK’s Component.removeNotify()
in Apache Commons Collections’ AbstractLinkedList.init()
in JFace’s ErrorDialog.createDropDownList(parent)
in JDK’s Object.equals(obj)
in JFace’s ViewerColumn
in JFace’s IDocumentAdapter
in JDK’s Format
in JFace’s AbstractInformationControl.create()
in JDK’s SecurityManager.checkAccess(t)
in JFace’s ErrorDialog
in JDK’s Condition
in JDK’s PrivilegedExceptionAction.run()
in JDK’s ClassLoader.getSystemClassLoader()
in JDK’s KeyStore.Builder.getProtectionParameter(alias)
in Apache Commons Collections’ ComparatorChain.ComparatorChain()
in JDK’s Inflater.setInput(b)
in JFace’s JFaceResources.setFontRegistry(registry)
in JDK’s ActivationGroup.createGroup(id, desc, incarnation)
in JDK’s Socket.setReceiveBufferSize(size)
in SWT’s Event.gc
in JDK’s File.delete()
in JDK’s Acl.removeEntry(caller, entry)
in JDK’s Object.wait(timeout)
in JFace’s DefaultAutoIndentStrategy
in JDK’s StringBuffer
in JFace’s ContentViewer.setInput(input)
in JDK’s HashMap
in Apache Commons Collections’ FixedSizeMap
in JDK’s BeanContextSupport.addAll(c)
in JDK’s CertStoreSpi
in JDK’s SuppressWarnings.value()
in JDK’s Statement.executeBatch()
in JFace OwnerDrawLabelProvider.erase(event, element)
in JDK’s Logger.setParent(parent)
We exclusively focus on API directives and not on other concerns of API documentation (audience, writing process, etc.). For a comprehensive discussion of these other concerns, we refer to the excellent paper written by a senior technical writer at Sun: “API documentation from source code comments: a case study of Javadoc” (Kramer 1999).
Alexander C, Ishikawa S, Silverstein M (1977) A pattern language: towns, buildings, construction. Oxford University Press
Arnout K, Meyer B (2003) Uncovering hidden contracts: the .net example. Comput 36:48–55
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.
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
Bloch J (2008) Effective java, 2nd edn. Addisson-Wesley
Bokowski B (2008) Java API design. In: Tutorial at the EclipseCon conference
Bokowski B, Arthorne J, des Rivières J (2006) Designing eclipse APIs. In: Tutorial at the EclipseCon conference
Bradner S (1997) Key words for use in rfcs to indicate requirement levels. Technical report, IETF
Brooks F (1995) The mythical man-month: essays on software engineering. Addison-Wesley
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
Clarke S (2004) Measuring API usability. Dr Dobb’s J 29(5):1–5
Cockburn A (2000) Writing effective use cases, 1st edn. Addison-Wesley Longman Publishing Co, Inc
Dekel U (2009) Increasing awareness of delocalized information to facilitate API usage. PhD thesis, Carnegie Mellon University
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
Easterbrook S, Singer J, Storey M-A, Damian D (2007) Selecting empirical methods for software engineering research
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
Gamma E, Helm R, Johnson RE, Vlissides J (1995) Design patterns: elements of reusable object-oriented software. Addison-Wesley
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
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
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
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
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
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
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
Robillard MP (2009) What makes APIs hard to learn? Answers from developers. IEEE Softw 26(6):27–34
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
Singh R, Mangat NS (1996) Elements of survey sampling. Springer
Smith KA, Kramer D (2003) Requirements for writing java API specifications. Technical report, Sun
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
Stylos J (2009) Making APIs more usable with improved API designs, documentation and tools. PhD thesis, Carnegie Mellon University
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
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
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)
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
Tan L, Yuan D, Krishna G, Zhou Y (2007) icomment: bugs or bad comments. In: Proceedings of the symposium on operating systems principles
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
Tulach J (2008) Practical API design: confessions of a java framework architect. Apress
Watson RB (2009) Improving software API usability through text analysis: a case study. In: Proceedings of the professional communication conference, pp 1–7
Ying ATT, Wright JL, Abrams S (2005) Source code that talks: an exploration of Eclipse task comments and their implication to repository mining. In: Proceedings of mining software repositories. ACM, pp 1–5
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
ADAM, University of Lille, Cité Scientifique, 59655, Villeneuve d’Ascq Cedex, France
Martin Monperrus
Software Technology Group, Darmstadt University of Technology, Hochschulstr. 10, 64289, Germany
Michael Eichberg & Mira Mezini
PSI Logistics GmBh, Boschstraße 6, 63741, Aschaffenburg, Germany
Elif Tekes
Correspondence to Martin Monperrus.
Electronic Supplementary MaterialBelow is the link to the electronic supplementary material.
About this article Cite this articleMonperrus, M., Eichberg, M., Tekes, E. et al. What should developers be aware of? An empirical study on the directives of API documentation. Empir Software Eng 17, 703–737 (2012). https://doi.org/10.1007/s10664-011-9186-4
Published: 03 December 2011
Issue Date: December 2012
DOI: https://doi.org/10.1007/s10664-011-9186-4
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4