Documentation generation from annotated source code of scientific software: Position paper

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.