POSITION PAPER: Documentation generation from annotated source code of scientific software

M. Moser. POSITION PAPER: Documentation generation from annotated source code of scientific software. pages 12-15, DOI 10.1145/2897676.2897679, 5, 2016.

Autoren
  • Michael Moser
BuchProceedings of the 2016 International Workshop on Software Engineering for Science - SE4Science 2016
TypIn Konferenzband
VerlagACM
DOI10.1145/2897676.2897679
ISBN978-1-4503-4167-7
Monat5
Jahr2016
Seiten12-15
Abstract

There is a widespread agreement in the scientific computing community that documentation positively influences software quality and thereby helps to mitigate the risk of project failure. We accompanied the introduction of a documentation generator within an industrial scientific computing project in order to automatically extract documentation from annotated C++ source code. Over a period of one year we extended and adopted the existing documentation generator RbG and performed some initial experiments to find out whether documentation generators can increment understandability and overall software quality of a scientific software system. However, although technically mature and adequate for the intended documentation tasks RbG was finally not used and the required documentation was created manually. In this paper we report on the adaption of the RbG, why it failed in this case study but potentially could improve software productivity and quality of scientific software.