DrylandEcology · dschlaep · Jan 24, 2022 · Jan 23, 2022 · Jan 23, 2022 · Jan 24, 2022
diff --git a/.github/workflows/check_doc.yml b/.github/workflows/check_doc.yml
@@ -0,0 +1,28 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  check_documentation:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v2
+      with:
+        submodules: recursive
+
+    - name: Install doxygen and dependencies
+      # SOILWAT2 documentation uses bibtex to build references
+      run: |
+        sudo apt-get update
+        sudo apt-get install doxygen doxygen-latex graphviz
+
+    - name: Build documentation and check for warnings
+      run: make clean doc
diff --git a/.github/workflows/main.yml → .github/workflows/main_nix.yml b/.github/workflows/main.yml → .github/workflows/main_nix.yml
@@ -1,7 +1,6 @@
-name: SOILWAT2 C/C++ CI
+name: tests
 
-#TODO: add gcc and clang versions
-#TODO: add doxygen documentation check
+#TODO: run unit tests with different compiler versions of both gcc and clang
 
 on:
   push:
@@ -12,7 +11,7 @@ on:
       - master
 
 jobs:
-  build:
+  build_nix:
 
     strategy:
       fail-fast: false
@@ -25,74 +24,41 @@ jobs:
       uses: actions/checkout@v2
       with:
         submodules: recursive
-      
+
     - name: Print compiler versions as seen by make
       run: make compiler_version
-    
+
     - name: Run binary
       run: |
         make clean bin bint_run
         make clean bin_debug_severe bint_run
 
     - name: Unit tests
       run: make clean test test_run
-        
+
     - name: Severe unit tests (without sanitizers)
       if: ${{ runner.os == 'macOS' }}
       run: make clean test_severe test_run
-      
+
     - name: Severe unit tests (with sanitizers)
       # Apple clang does not support "AddressSanitizer: detect_leaks" (at least as of clang-1200.0.32.29)
       if: ${{ runner.os != 'macOS' }}
       run: ASAN_OPTIONS=detect_leaks=1:strict_string_checks=1:detect_stack_use_after_return=1:check_initialization_order=1:strict_init_order=1 LSAN_OPTIONS=suppressions=.LSAN_suppr.txt make clean test_severe test_run
-
-    - name: Generate coverage report (ubuntu)
-      if: ${{ runner.os == 'Linux' && success() }}
-      run: make clean cov cov_run
 
-    - name: Upload coverage to Codecov (ubuntu)
-      if: ${{ runner.os == 'Linux' && success() }}
-      uses: codecov/codecov-action@v2
-      with:
-        fail_ci_if_error: false # just report, don't fail checks
-
-
-  build_Windows_Cygwin:
-    # see https://github.com/cygwin/cygwin-install-action
-    # based on https://github.com/resurrecting-open-source-projects/scrot
-
-    runs-on: windows-latest
-    env:
-      CYGWIN_NOWINPATH: 1 # only have cygwin's executables on PATH
-      CHERE_INVOKING: 1 # prevent profile script to change directory
-    defaults:
-      run:
-        shell: C:\cygwin\bin\bash.exe --login -eo pipefail -o igncr {0}
 
+  check_code_coverage:
+    runs-on: ubuntu-latest
+
     steps:
-    - run: git config --global core.autocrlf input
-      shell: bash
-
     - name: Checkout repository and submodules
       uses: actions/checkout@v2
       with:
         submodules: recursive
-
-    - name: Install cygwin (windows)
-      uses: cygwin/cygwin-install-action@v1
-      with:
-        packages: gcc-core make
-
-    - name: Print compiler versions as seen by make
-      run: make compiler_version
-
-    - name: Run binary
-      run: |
-        make clean bin bint_run
-        make clean bin_debug_severe bint_run
 
-    - name: Unit tests
-      run: make clean test test_run
-
-    - name: Severe unit tests (without sanitizers)
-      run: make clean test_severe test_run
+    - name: Generate coverage report
+      run: make clean cov cov_run
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v2
+      with:
+        fail_ci_if_error: false # just report, don't fail checks
diff --git a/.github/workflows/main_win.yml b/.github/workflows/main_win.yml
@@ -1,4 +1,4 @@
-name: SOILWAT2 cygwin CI
+name: win-tests
 
 #TODO: run unit tests with different compiler versions of both gcc and clang
 

diff --git a/README.md b/README.md
@@ -1,12 +1,19 @@
-| *nix | Windows | Release | DOI | License | Coverage |
-| :---- | :---- | :---- | :---- | :---- | :---- |
-[ ![Travis build status][1]][2] | [![Appveyor build status][3]][4] | [ ![github release][5]][6] | [ ![DOI][7]][8] | [![license][9]][10] | [![codecov status][11]][12] |
+<!-- badges: start -->
+[![gh nix build status][1]][2]
+[![gh win build status][3]][2]
+[![github release][5]][6]
+[![DOI][7]][8]
+[![license][9]][10]
+[![codecov status][11]][12]
+[![doc status][4]][2]
+<!-- badges: end -->
+
+
+[1]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/main_nix.yml/badge.svg?branch=master
+[2]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows
+[3]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/main_win.yml/badge.svg?branch=master
+[4]: https://github.com/DrylandEcology/SOILWAT2/actions/workflows/check_doc.yml/badge.svg?branch=master
 
-
-[1]: https://travis-ci.org/DrylandEcology/SOILWAT2.svg?branch=master
-[2]: https://travis-ci.org/DrylandEcology/SOILWAT2
-[3]: https://ci.appveyor.com/api/projects/status/noes9lralyjhen3t/branch/master?svg=true
-[4]: https://ci.appveyor.com/project/DrylandEcologyGit/soilwat2/branch/master
 [5]: https://img.shields.io/github/release/DrylandEcology/SOILWAT2.svg
 [6]: https://github.com/DrylandEcology/SOILWAT2/releases
 [7]: https://zenodo.org/badge/9551524.svg
@@ -15,6 +22,7 @@
 [10]: https://www.gnu.org/licenses/gpl.html
 [11]: https://codecov.io/gh/DrylandEcology/SOILWAT2/branch/master/graph/badge.svg
 [12]: https://codecov.io/gh/DrylandEcology/SOILWAT2
+
 [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2
 [rSOILWAT2]: https://github.com/DrylandEcology/rSOILWAT2
 [STEPWAT2]: https://github.com/DrylandEcology/STEPWAT2
@@ -75,14 +83,19 @@ Some recent references
 <a name="get_started"></a>
 ## How to get started
 
-A detailed manual can be found
-[here](`doc/additional_pages/A SOILWAT2 user guide.md`) or here \ref page_manual.
+SOILWAT2 comes with a
+[detailed manual](doc/additional_pages/A_SOILWAT2_user_guide.md)
+and short overviews of
+[inputs](doc/additional_pages/SOILWAT2_Inputs.md)
+and [outputs](doc/additional_pages/SOILWAT2_Outputs.md).
+A full code documentation may be built, see [here](#get_documentation).
+
 
 <a name="compile"></a>
 ### Compilation
   * Requirements:
     - the `gcc` or `clang/llvm` toolchains
-      - `gcc >= v4.9` and `clang >= v3.3` for the `*_severe` test/debug targets
+      - `gcc >= v5` and `clang >= v5` for the `*_severe` test/debug targets
     - POSIX- or GNU-compliant `make`
     - On Windows OS: an installation of `cygwin`
 
@@ -240,7 +253,7 @@ following output is implemented:
 __Continous integration checks__
 
 Development/feature branches can only be merged into master if they pass
-all checks on `appveyor` and `travis` continuous integration servers, i.e.,
+all checks on the continuous integration servers, i.e.,
 run the following locally to prepare a pull-request or commit to be reviewed
 ```{.sh}
       make clean bin_debug_severe bint_run

diff --git a/SW_Flow_lib.c b/SW_Flow_lib.c
@@ -509,18 +509,16 @@ void pot_soil_evap(double *bserate, unsigned int nelyrs, double ecoeff[], double
 
 Based on equations from Parton 1978. @cite Parton1978
 
-@param *bserate Bare soil evaporation loss rate (cm/day).
-@param nelyrs Number of layers to consider in evaporation.
-@param ecoeff Array of evaporation coefficients.
-@param petday Potential evapotranspiration rate (cm/day).
-@param shift Displacement of the inflection point in order to shift the function up, down, left, or right.
-@param shape Slope of the line at the inflection point.
-@param inflec Y-value of the inflection point.
-@param range Max y-value - min y-value at the limits.
-@param width Width of each layer (cm).
-@param swc Soilwater content in each layer before drainage (m<SUP>3</SUP> H<SUB>2</SUB>O).
-
-@return *bserate Updated bare soil evaporation loss rate (cm/day).
+@param[in,out] *bserate Bare soil evaporation loss rate (cm/day).
+@param[in] nelyrs Number of layers to consider in evaporation.
+@param[in] ecoeff Array of evaporation coefficients.
+@param[in] petday Potential evapotranspiration rate (cm/day).
+@param[in] shift Displacement of the inflection point in order to shift the function up, down, left, or right.
+@param[in] shape Slope of the line at the inflection point.
+@param[in] inflec Y-value of the inflection point.
+@param[in] range Max y-value - min y-value at the limits.
+@param[in] width Width of each layer (cm).
+@param[in] swc Soilwater content in each layer before drainage (m<SUP>3</SUP> H<SUB>2</SUB>O).
 
 */
 
@@ -1096,15 +1094,14 @@ void lyrSoil_to_lyrTemp_temperature(unsigned int nlyrSoil, double depth_Soil[],
 @brief Initialize soil temperature layer values by transfering soil layer values
     to soil temperature layer values.
 
-@param cor Two dimensional array containing soil temperature data.
-@param nlyrSoil Number of soil layers.
-@param width_Soil Width of the soil layers.
-@param var Soil layer values to be interpolated.
-@param nlyrTemp Number of soil temperature layers.
-@param width_Temp Width of the soil temperature layers.
-@param res Values interpolated to soil temperature depths.
+@param[in] cor Two dimensional array containing soil temperature data.
+@param[in] nlyrSoil Number of soil layers.
+@param[in] width_Soil Width of the soil layers.
+@param[in] var Soil layer values to be interpolated.
+@param[in] nlyrTemp Number of soil temperature layers.
+@param[in] width_Temp Width of the soil temperature layers.
+@param[in,out] res Values interpolated to soil temperature depths.
 
-@return res is updated and reflects new values.
 */
 
 void lyrSoil_to_lyrTemp(double cor[MAX_ST_RGR][MAX_LAYERS + 1], unsigned int nlyrSoil,

diff --git a/SW_Model.c b/SW_Model.c
@@ -166,7 +166,7 @@ void SW_MDL_read(void) {
 	cnt = 0;
 	while (GetALine(f, inbuf)) {
 		cnt++;
-		if (isalpha(*inbuf) && strcmp(inbuf, "end")) { /* get hemisphere */
+		if (isalpha((int) *inbuf) && strcmp(inbuf, "end")) { /* get hemisphere */
 			m->isnorth = (Bool) (toupper((int) *inbuf) == 'N');
 			fhemi = swTRUE;
 			break;

diff --git a/SW_Output_outtext.c b/SW_Output_outtext.c
@@ -376,7 +376,6 @@ void get_outstrleader(OutPeriod pd, char *str) {
   \param does_agg Indicate whether output is aggregated (`-o` option) or
     for each SOILWAT2 run (`-i` option)
 
-  \return void.
 */
 void write_headers_to_csv(OutPeriod pd, FILE *fp_reg, FILE *fp_soil, Bool does_agg) {
 	char str_time[20];

diff --git a/...additional_pages/A SOILWAT2 user guide.md → ...additional_pages/A_SOILWAT2_user_guide.md b/...additional_pages/A SOILWAT2 user guide.md → ...additional_pages/A_SOILWAT2_user_guide.md
@@ -1,5 +1,4 @@
-\page page_manual A SOILWAT2 user guide
-
+# A SOILWAT2 user guide
 
 [clang/llvm]: https://clang.llvm.org
 [cygwin]: https://www.cygwin.com
@@ -14,6 +13,10 @@
 [xcode]: https://developer.apple.com/xcode
 
 
+Note: this document is best viewed as part of the doxygen-built documentation
+(there may be text artifacts if viewed as standalone-markdown).
+
+
 The `SOILWAT2` program must be downloaded as source code and compiled from the
 command line. The program is written in `C` and has no graphical user interface.
 If you are more familiar with `R`, then you may prefer to use our R package
@@ -35,7 +38,7 @@ on your side.
 ### Minimal requirements
   - on any platform:
     - the [gcc][] or [clang/llvm][] toolchains;
-      ideally, `gcc >= v4.9` or `clang >= v3.3`
+      ideally, `gcc >= v4.9` or `clang >= v3.3` (at least `v5.0` for testing)
     - POSIX- [make](https://pubs.opengroup.org/onlinepubs/9699919799/) or
       GNU-compliant [make](https://www.gnu.org/software/make/)
     - [git][] to download the code
@@ -107,13 +110,16 @@ on your side.
 
 
 ### Documentation
-  * Generate help pages (locally) and open them in your browser
+  * Code documentation
 ```{.sh}
     cd SOILWAT2/
     make doc
     make doc_open
 ```
 
+  * Documentation of user inputs and outputs
+    * \subpage doc/additional_pages/SOILWAT2_Inputs.md "SOILWAT2 Inputs"
+    * \subpage doc/additional_pages/SOILWAT2_Outputs.md "SOILWAT2 Outputs"
 <br>
 
 
@@ -134,16 +140,18 @@ on your side.
 ```
 
   * The inputs comprise the master file `files.in` and the content of the
-    `Input/` folder. They are explained in detail \subpage page_inputs "here".
+    `Input/` folder. They are explained in detail
+    [here](doc/additional_pages/SOILWAT2_Inputs.md).
   * The outputs are written to `Output/` including a logfile that contains
     warnings and errors. The output files are in `.csv` format and can be
     opened by a spreadsheet program (e.g., `LibreOffice` or `Excel`) or
     imported into `R`
     (e.g., `data <- read.csv("testing/Output/sw2_yearly.csv")`).
-    Outputs are explained in detail \subpage page_outputs "here".
+    Outputs are explained in detail
+    [here](doc/additional_pages/SOILWAT2_Inputs.md).
 
 <br>
 
 <hr>
-Go back to the \ref index "main page".
+Go back to the [main page](README.md).
 
diff --git a/doc/additional_pages/SOILWAT2 Inputs.md → doc/additional_pages/SOILWAT2_Inputs.md b/doc/additional_pages/SOILWAT2 Inputs.md → doc/additional_pages/SOILWAT2_Inputs.md
@@ -1,7 +1,11 @@
-\page page_inputs SOILWAT2 Inputs
+# SOILWAT2 Inputs
 
 [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2
 
+Note: this document is best viewed as part of the doxygen-built documentation
+(there may be text artifacts if viewed as standalone-markdown).
+
+
 ### Example
   * The source code contains a complete example simulation project in `testing/`
   * Copy the executable to the testing path, modify inputs as desired,
@@ -22,7 +26,7 @@
     \ref explain_inputs "below".
   * The outputs are written to `Output/` including a logfile that contains
     warnings and errors. Outputs are explained in detail
-    \ref page_outputs "here".
+    [here](doc/additional_pages/SOILWAT2_Outputs.md).
 
 <br>
 
@@ -131,4 +135,5 @@ Go back to the \ref explain_inputs "list of input files"
 
 
 <hr>
-Go back to the \ref index "main page" or the \ref page_manual "user guide".
+Go back to the [main page](README.md) or
+[user guide](doc/additional_pages/A_SOILWAT2_user_guide.md).