2012 Annual Report
1a.Objectives (from AD-416):
The purpose of this agreement is for the United States Department of Agriculture, Agricultural Research Service (ARS), to continue development, programming, debugging, and documentation of the computer code of the Revised Universal Soil Loss Equation (RUSLE2) (Version.
2)for use by Natural Resources Conservation Service (NRCS). RUSLE2 is the water erosion prediction tool for use by NRCS.
1b.Approach (from AD-416):
1. Create additional Doxygen project(s) to document the Revised Universal Soil Loss Equation (RUSLE2) science code and integrate them to the existing documentation.
2. Create documentation describing all the separate modules, classes, functions and files in Rusle2 using Doxygen, and produce high-level overviews describing the several model components.
3. Convert existing Rusle2 documentation in other formats (Microsoft Word documents, Rich Text Format, etc) into the Doxygen format and integrate those into the rest of the documentation.
4. Document the implementation of science functions by adding references to appropriate sections, pages, or equations in the existing RUSLE2 Users Guide and RUSLE2 Science Documentation.
The Revised Universal Soil Loss Equation – Version 2 (RUSLE2) is a very large simulation software, programmed in the C++ computer language. Due to its complex software architecture, understanding how program units interact can be challenging to new programmers. Modifications and extensions to the RUSLE2 software require care and comprehensive knowledge of the computer code. In order to facilitate the understanding of the program’s intricacies, maintain software quality, and minimize the risk of introduction of errors, it became necessary to develop and maintain an accurate and up-to-date technical documentation of the several components of the program.
Comprehensive software design and source code documentation was created using automated software documentation procedures. Program documentation reports can now be automatically generated using the documentation system for source code (Doxygen) (www.doxygen.org) documentation system, which generates an on-line documentation browser (in hyper-text markup language (HTML)) based on the analysis of the source code structure, instructions and notes added directly to the source code, and external documentation files. The resulting document permits a programmer to navigate through the various modules and visualize the relations between the various elements by means of dependency graphs, and inheritance and collaboration diagrams, which are all generated automatically.
A Computer Programmer, located at the Arkansas State University campus in Jonesboro, Arkansas, was hired to support the development of required software tools, analyze RUSLE2 source code, insert required comments and notes, and develop “Doxygen” projects for the generation of automated documentation. Technical meetings with RUSLE2 developers were conducted to discuss the RUSLE2 software architecture, source code structure, and other programming and software maintenance issues. The meetings were conducted at the University of Tennessee, Knoxville, TN, in March 2012, and at the NRCS Information Technology Center in Ft. Collins, CO, in May 2012.
An important component of the new documentation system is the establishment of automated links between lines of software code to passages and equations in the “RUSLE2 Science Documentation”, which permit verification of the software code against the Science Documentation. To successfully implement this feature, the existing Science Documentation was reformatted so that all document sections and equations were numbered automatically. Programs were written to convert the contents of the Science Document into HTML files that could be integrated into the software documentation. The new software documentation system also organizes and integrates older documents. A new documentation report can now be quickly recreated to reflect changes in either the source code or in the Science Documentation.