udoxy

Guidelines and script for generic documentation of source code implemented in various programming languages (bash/Perl/Python/R/Matlab/SAS/Stata/DOS/...).

We provide hereby a set of common guidelines and templates for a generic inline source code documentation (using markdown language) as well as a bash script for the automatic generation of a derived online documentation (using Doxygen generator).

Description

We adopt a common way for describing and documenting stand-alone source code/programs regardless of the platform (language, software) used for the implementation. In practice, the source code documentation will be made available not only as an inline documentation (visible by those who actually implement the code, e.g. through comments in the code), but as a portable document (visible by those who run the code, e.g. through a browsable interface like html) as well:

• an "inline" documentation is systematically inserted in the header (e.g., top of the program file storing a macro, a function, etc...),
• this documentation appears as comments inside the programs (e.g., in between /* and */ marks for many languages),
• human-readable language markdown is adopted for writing the source code documentation,
• a (bash) script, namely src2mddoc.sh, for the automatic extraction of the formatted documentation header from the source files,
• documentation generator Doxygen is used to generate a user-friendly browsable "online" documentation.

Note that this way, it is not necessary to "group" the source code that is documented (it can be left as is, in its original location), instead it is enough to "centralise" the markdown generated files (though this could be avoided as well).

Example of "agnostic" documentation using the same generic templates.

Table of Contents

• rationale: Rationale behind these choices (of documentation language, of documentation generator,...) that have been made.
• guidelines: Set of guidelines used for the documentation of various programs (function/macro/script/...) in different languages, e.g.
  • generic template,
  • SAS rules,
  • Stata rules,
  • R rules,
  • Python rules,
  • bash rules,
  • Matlab rules,
  • DOS rules;
• usage: Usage of the script for the extraction of the documentation;
• examples: Examples of generation of online browsable documentation.

Notes

This material aims at supporting the development, sharing and reuse of open IT components, e.g., deployed in production environment, and ensuring complete transparency of in-house computational resources, e.g. regardless of the platform used for the implementation (Grazzini and Pantisano, 2015; Grazzini and Lamarche, 2017).

The approach proposed herein is adapted to the documenting of stand-alone programs and processes. It can be can easily be extended (e.g., slightly adapting the guidelines and tools) to support other software/programing languages.

About

documentation	available at: https://eurostat.github.io/udoxy/
status	since 2016 – closed
contributors
license	EUPL

References

• Grazzini J. and Lamarche P. (2017): Production of social statistics... goes social!, in Proc. New Techniques and Technologies for Statistics.
• Grazzini J. and Pantisano F. (2015): Collaborative research-grade software for crowd-sourced data exploration: from context to practice - Part I: Guidelines for scientific evidence provision for policy support based on Big Data and open technologies, Publications Office of the European Union, doi:10.2788/329540.
• Doxygen main page.
• dexy webpage.