nach oben

Empirical Software Engineering

Erschienen in:

01.12.2012

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

verfasst von: Martin Monperrus, Michael Eichberg, Elif Tekes, Mira Mezini

Erschienen in: Empirical Software Engineering | Ausgabe 6/2012

Einloggen

Aktivieren Sie unsere intelligente Suche, um passende Fachinhalte oder Patente zu finden.

search-config

KI-gestützte Suche

Aus

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.

Vorheriger Artikel Strengths and barriers behind the successful agile deployment—insights from the three software intensive companies in Finland

Nächster Artikel Software development effort prediction of industrial projects applying a general regression neural network

Sie haben noch keine Lizenz? Dann Informieren Sie sich jetzt über unsere Produkte:

Springer Professional "Wirtschaft"

Online-Abonnement

Mit Springer Professional "Wirtschaft" erhalten Sie Zugriff auf:

über 67.000 Bücher
über 340 Zeitschriften

aus folgenden Fachgebieten:

Bauwesen + Immobilien
Business IT + Informatik
Finance + Banking
Management + Führung
Marketing + Vertrieb
Versicherung + Risiko

Jetzt Wissensvorsprung sichern!

Jetzt informieren

Springer Professional "Technik"

Online-Abonnement

Mit Springer Professional "Technik" erhalten Sie Zugriff auf:

über 67.000 Bücher
über 390 Zeitschriften

aus folgenden Fachgebieten:

Automobil + Motoren
Bauwesen + Immobilien
Business IT + Informatik
Elektrotechnik + Elektronik
Energie + Nachhaltigkeit
Maschinenbau + Werkstoffe

Jetzt Wissensvorsprung sichern!

Jetzt informieren

Springer Professional "Wirtschaft+Technik"

Online-Abonnement

Mit Springer Professional "Wirtschaft+Technik" erhalten Sie Zugriff auf:

über 102.000 Bücher
über 537 Zeitschriften

aus folgenden Fachgebieten:

Automobil + Motoren
Bauwesen + Immobilien
Business IT + Informatik
Elektrotechnik + Elektronik
Energie + Nachhaltigkeit
Finance + Banking
Management + Führung
Marketing + Vertrieb
Maschinenbau + Werkstoffe
Versicherung + Risiko

Jetzt Wissensvorsprung sichern!

Jetzt informieren

Nur mit Berechtigung zugänglich

Eclipse is an extensible development environment primarily targeted for Java.

See http://jgrapht.sourceforge.net.

See http://www.oracle.com/technetwork/java/javase/index.html.

See http://www.microsoft.com/net/.

See http://www.boost.org/.

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/.

See http://wiki.eclipse.org/index.php/JFace.

$ cvs -d :pserver:anonymous@dev.eclipse.org/cvsroot/eclipse/ co -D “15 Oct 2009” org.eclipse.jface

See http://commons.apache.org/collections/.

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()

See http://en.wikipedia.org/wiki/Abundance_(ecology).

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–55CrossRef

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–19CrossRef

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–34CrossRef

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–112CrossRef

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

Titel: What should developers be aware of? An empirical study on the directives of API documentation
verfasst von: Martin Monperrus
Michael Eichberg
Elif Tekes
Mira Mezini
Publikationsdatum: 01.12.2012
Verlag: Springer US
Erschienen in: Empirical Software Engineering / Ausgabe 6/2012
Print ISSN: 1382-3256
Elektronische ISSN: 1573-7616
DOI: https://doi.org/10.1007/s10664-011-9186-4

Springer Professional

Abstract

Bitte loggen Sie sich ein, um Zugang zu Ihrer Lizenz zu erhalten.

Sie haben noch keine Lizenz? Dann Informieren Sie sich jetzt über unsere Produkte:

Springer Professional "Wirtschaft"

Springer Professional "Technik"

Springer Professional "Wirtschaft+Technik"

Weitere Artikel der Ausgabe 6/2012

Developing a grounded theory to explain the practices of self-organizing Agile teams

Computer-mediated communication to support distributed requirements elicitations and negotiations tasks

Strengths and barriers behind the successful agile deployment—insights from the three software intensive companies in Finland

Software development effort prediction of industrial projects applying a general regression neural network

Premium Partner