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

Autoren Michael Moser
Josef Pichler
Editoren
TitelPOSITION PAPER: Documentation generation from annotated source code of scientific software
BuchtitelProceedings of the 2016 International Workshop on Software Engineering for Science - SE4Science 2016
Typin Konferenzband
VerlagACM
ISBN978-1-4503-4167-7
DOI10.1145/2897676.2897679
MonatMay
Jahr2016
Seiten12-15
SCCH ID#1620
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.