Skip to main content
Springer Nature Link
Log in

Documentation Reuse: Hot or Not? An Empirical Study

  • Conference paper
  • First Online:
Mastering Scale and Complexity in Software Reuse (ICSR 2017)

Part of the book series: Lecture Notes in Computer Science ((LNPSE,volume 10221))

Included in the following conference series:

  • 851 Accesses

Abstract

Having available a high quality documentation is critical for software projects. This is why documentation tools such as Javadoc are so popular. As for code, documentation should be reused when possible to increase developer productivity and simplify maintenance. In this paper, we perform an empirical study of duplications in JavaDoc documentation on a corpus of seven famous Java APIs. Our results show that copy-pastes of JavaDoc documentation tags are abundant in our corpus. We also show that these copy-pastes are caused by four different kinds of relations in the underlying source code. In addition, we show that popular documentation tools do not provide any reuse mechanism to cope with these relations. Finally, we make a proposal for a simple but efficient automatic reuse mechanism.

This is a preview of subscription content, log in via an institution to check access.

Access this chapter

Log in via an institution

Subscribe and save

Springer+ Basic
$34.99 /Month
  • Get 10 units per month
  • Download Article/Chapter or eBook
  • 1 Unit = 1 Article or 1 Chapter
  • Cancel anytime
Subscribe now

Buy Now

Chapter
USD 29.95
Price excludes VAT (USA)
  • Available as PDF
  • Read on any device
  • Instant download
  • Own it forever

Tax calculation will be finalised at checkout

Purchases are for personal use only

Institutional subscriptions

Similar content being viewed by others

Notes

  1. 1.

    http://se.labri.fr/a/ICSR17-oumaziz.

  2. 2.

    https://github.com/docreuse/docreuse.

  3. 3.

    http://se.labri.fr/a/ICSR17-oumaziz/RandomExperiment.

  4. 4.

    http://se.labri.fr/a/ICSR17-oumaziz.

  5. 5.

    https://en.wikipedia.org/wiki/Comparison_of_documentation_generators.

  6. 6.

    http://se.labri.fr/a/ICSR17-oumaziz.

References

  1. Buse, R.P., Weimer, W.R.: Automatic documentation inference for exceptions. In: Proceedings of the 2008 International Symposium on Software Testing and Analysis, pp. 273–282. ACM (2008)

    Google Scholar 

  2. Charpentier, A., Falleri, J.R., Lo, D., Réveillère, L.: An empirical assessment of Bellon’s clone benchmark. In: Proceedings of the 19th International Conference on Evaluation and Assessment in Software Engineering, EASE 2015, pp. 20:1–20:10. ACM, Nanjing (2015)

    Google Scholar 

  3. Childs, B., Sametinger, J.: Literate programming and documentation reuse. In: Proceedings of Fourth International Conference on Software Reuse, pp. 205–214. IEEE (1996)

    Google Scholar 

  4. Correia, F.F., Aguiar, A., Ferreira, H.S., Flores, N.: Patterns for consistent software documentation. In: Proceedings of the 16th Conference on Pattern Languages of Programs, p. 12. ACM (2009)

    Google Scholar 

  5. Dagenais, B., Robillard, M.P.: Creating and evolving developer documentation: understanding the decisions of open source contributors. In: Proceedings of the Eighteenth ACM SIGSOFT International Symposium on Foundations of Software Engineering, pp. 127–136. ACM (2010)

    Google Scholar 

  6. Efron, B., Tibshirani, R.J.: An Introduction to the Bootstrap. Chapman & Hall, New York (1993)

    Book  MATH  Google Scholar 

  7. Falleri, J.R., Morandat, F., Blanc, X., Martinez, M., Monperrus, M.: Fine-grained and accurate source code differencing. In: Proceedings of the 29th ACM/IEEE International Conference on Automated Software Engineering, ASE 2014, pp. 313–324. ACM, New York (2014)

    Google Scholar 

  8. Fluri, B., Würsch, M., Gall, H.C.: Do code and comments co-evolve? on the relation between source code and comment changes. In: 14th Working Conference on Reverse Engineering, WCRE 2007, pp. 70–79. IEEE (2007)

    Google Scholar 

  9. Forward, A., Lethbridge, T.C.: The relevance of software documentation, tools and technologies: a survey. In: Proceedings of the 2002 ACM Symposium on Document Engineering, DocEng 2002, NY, USA, pp. 26–33. ACM, New York (2002)

    Google Scholar 

  10. Ganter, B., Wille, R.: Formal Concept Analysis: Mathematical Foundations, 1st edn. Springer-Verlag, Secaucus (1997)

    MATH  Google Scholar 

  11. Juergens, E., Deissenboeck, F., Hummel, B., Wagner, S.: Do code clones matter? In: IEEE 31st International Conference on Software Engineering, ICSE 2009, pp. 485–495, May 2009

    Google Scholar 

  12. Kramer, D.: API documentation from source code comments: a case study of Javadoc. In: Proceedings of the 17th Annual International Conference on Computer Documentation, pp. 147–153. ACM (1999)

    Google Scholar 

  13. Lakhotia, A.: Understanding someone else’s code: analysis of experiences. J. Syst. Softw. 23(3), 269–275 (1993)

    Article  MathSciNet  Google Scholar 

  14. Lethbridge, T.C., Singer, J., Forward, A.: How software engineers use documentation: the state of the practice. IEEE Softw. 20(6), 35–39 (2003)

    Article  Google Scholar 

  15. McBurney, P.W., McMillan, C.: Automatic documentation generation via source code summarization of method context. In: Proceedings of the 22nd International Conference on Program Comprehension, pp. 279–290. ACM (2014)

    Google Scholar 

  16. Monperrus, M., Eichberg, M., Tekes, E., Mezini, M.: What should developers be aware of? an empirical study on the directives of API documentation. Empirical Softw. Eng. 17(6), 703–737 (2012)

    Article  Google Scholar 

  17. Parnas, D.L.: A technique for software module specification with examples. Commun. ACM 15(5), 330–336 (1972)

    Article  Google Scholar 

  18. Parnas, D.L.: Software aging. In: Proceedings of the 16th International Conference on Software Engineering, pp. 279–287. IEEE Computer Society Press (1994)

    Google Scholar 

  19. Pierce, R., Tilley, S.: Automatically connecting documentation to code with rose. In: Proceedings of the 20th Annual International Conference on Computer Documentation, pp. 157–163. ACM (2002)

    Google Scholar 

  20. Pollack, M.: Code generation using Javadoc. JavaWorld (2000). http://www.javaworld.com/javaworld/jw-08-2000/jw-0818-javadoc.html

  21. Robillard, M.P., Chhetri, Y.B.: Recommending reference API documentation. Empirical Softw. Eng. 20(6), 1558–1586 (2015)

    Article  Google Scholar 

  22. de Souza, S.C.B., Anquetil, N., de Oliveira, K.M.: A study of the documentation essential to software maintenance. In: Proceedings of the 23rd Annual International Conference on Design of Communication: Documenting & Designing for Pervasive Information, SIGDOC 2005, pp. 68–75. ACM, New York (2005)

    Google Scholar 

  23. Teyton, C., Falleri, J.R., Palyart, M., Blanc, X.: A study of library migrations in Java. J. Softw. Evol. Process 26(11), 1030–1052 (2014)

    Article  Google Scholar 

  24. Van Heesch, D.: Doxygen (2004)

    Google Scholar 

  25. Van De Vanter, M.L.: The documentary structure of source code. Inf. Softw. Technol. 44(13), 767–782 (2002). Special Issue on Source Code Analysis and Manipulation (SCAM)

    Article  Google Scholar 

  26. Zhong, H., Su, Z.: Detecting API documentation errors. In: ACM SIGPLAN Notices, vol. 48, pp. 803–816. ACM (2013)

    Google Scholar 

Download references

Author information

Authors and Affiliations

  1. CNRS, Bordeaux INP, Univ. Bordeaux LaBRI, UMR 5800, 33400, Talence, France

    Mohamed A. Oumaziz, Alan Charpentier, Jean-Rémy Falleri & Xavier Blanc

Authors
  1. Mohamed A. Oumaziz
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Alan Charpentier
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Jean-Rémy Falleri
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Xavier Blanc
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Mohamed A. Oumaziz .

Editor information

Editors and Affiliations

  1. Lero - University of Limerick, Limerick, Ireland

    Goetz Botterweck

  2. Federal University of Rio de Janeiro, Rio de Janeiro, Brazil

    Claudia Werner

Rights and permissions

Reprints and permissions

Copyright information

© 2017 Springer International Publishing AG

About this paper

Cite this paper

Oumaziz, M.A., Charpentier, A., Falleri, JR., Blanc, X. (2017). Documentation Reuse: Hot or Not? An Empirical Study. In: Botterweck, G., Werner, C. (eds) Mastering Scale and Complexity in Software Reuse. ICSR 2017. Lecture Notes in Computer Science(), vol 10221. Springer, Cham. https://doi.org/10.1007/978-3-319-56856-0_2

Download citation

  • DOI: https://doi.org/10.1007/978-3-319-56856-0_2

  • Published:

  • Publisher Name: Springer, Cham

  • Print ISBN: 978-3-319-56855-3

  • Online ISBN: 978-3-319-56856-0

  • eBook Packages: Computer ScienceComputer Science (R0)

Publish with us

Policies and ethics