Unit tests added for the following functions; svapor, petfunc, transp_weighted_avg, EsT_partitioning, pot_soil_evap, pot_soil_evap_bs, pot_transp, watrate, evap_fromSurface, remove_from_soil, infiltrate_water_low.  infiltrate_water_low is lacking complete documentation.

Added unit tests for hydraulic_redistribution

Updated documentation and citations for SW_Flow_lib.c, SW_SoilWater.c, and SOILWAT2.bib

Added missing files to .bib file

Updated documentation

Updated documentaion for SW_Flow_lib.c and W_SoilWater.c, changed unit test for infiltrate_water_high function from EXPECT_DOUBLE_EQ to EXPECT_NEAR

Updated failing tests that were affected by if (st->lyrFrozen[i]) statements

Replaced all instances of EXPECT_DOUBLE_EQ combined with rounding with EXPECT_NEAR

Fixed failing tests dealing with st->lyrFrozen[i]

Fixed remaining failing tests at line 940.

Changes made to tests affected by if (st->lyrFrozen[i]) causing them to fail

Simplified a failing group of tests due to st->yrFrozen[i]  receiving a load of value 1372188672, which is not a valid value for type 'Bool'

Changed EXPECT_LT(sTemp3[k], 100); to EXPECT_LT(sTemp3[k], 1000); at ln 569.

…17_Connor

Added multiple resets.  Undid change to line 569 of test_SW_Flow_lib_temp.cc

Changes not completed are those involving testing at nlyrs = MAX_LAYERS instead of nlyrs = 8.  Explanation on github.

Function was required to prevent segmentation fault during unit testing, unit tests will be pushed when all are passing.

Still segmentation faulting.

- document function with doxygen comments (there is more that needs to be documented)
- gained new argument `nlyrs`: the number of soil layers to create --> otherwise, `MAX_LAYERS` are created whether or not the input arguments hold sufficient data
- must first de-allocate previous soil layers --> otherwise, "the first member of the user defined input array to be set at i=8(9th spot in array) instead of at i=0. I am not sure why this is happening" (#218 (comment))
- must set `my_transp_rgn[k]` and `n_transp_lyrs[k]` as well as `n_evap_lyrs` for each new soil layer
- must call `init_site_info` to re-initialize site parameters based on new soil layers

- function `_set_layers` now expects the number of soil layers to create as first argument
- the second argument, here variable `dmax`, is an array of the lower soil layer depths -- not soil layer widths

…17_Connor

Unit test is now working with _set_layers function

Test in test_SW_Flow_Lib.cc is passing with help of _set_layers function from sw_testhelpers.cc  Commented out some print statements in _set_layers function but these will most likely need to be removed later.

Tests passing for remove_from_soil test with addition of _set_layers function

Tests are passing for hydraulic_redistribution function at 25 layers with help of _set_layers function.

Changed number of layers from 8 to 25 and adjusted input arrays accordingly.

index k was previously unset in line 653:
if(v->veg[k].Es_param_limit > 600)

temporarily removing svapor test, will re add after merging files, git kraken doesn't allow editing of output file unless you upgrade to kit kraken pro

This reverts commit 1173f8e.

Resolving merge conflicts

Function veg_intercepted_water of test_SW_Flow_Lib.cc did not merge correctly on past attempt.  Tests for the updated version of this function are passing

Updated unit tests for functions; transp_weighted_avg, pot_soil_evap, & pot_soil_evap by updating values for swc inputs and affected outputs used in testing.

No matter the inputs for totagb and Es_param_limit, the output variable, bserate == 0, for function pot_soil_evap, these tests have been temporarily commented out

- enhancements to function `pot_soil_evap`
* weighted soil moisture average is calculated only over soil layers with evaporation coefficient > 0
* average prevents division by zero
* function returns a zero potential rate if there is no soil moisture

- unit tests for function `pot_soil_evap`
* removed hard coded value tests --> avoid such fixed values where-ever reasonable and replace by tests against physical bounds, e.g., these new unit tests (@cjb643)
* add tests for physically reasonable bounds (0 <= rate; rate <= PET; rate <= potential rate)
* added different scenarios:  PET = 0 or > 0; potential rate = 0 or > 0; swc = 0 or > 0
* also addresses comment by @cjb643 in commit 4b9e343, i.e., previously `watrate` returned 0 because of physically impossible soil layer values

- new helper function `create_test_soillayers` that sets up a consistent soil layer structure for unit testing
* used in new unit tests for function `pot_soil_evap`
* added as example in unit tests for function `transp_weighted_avg`
--> should be used throughout unit tests, i.e., replace repeated in-code soil array definitions and setup with `_set_layers` where adequate (@cjb643)

replaced repeated in-code soil array definitions and setup with `_set_layers` for functions; pot_soil_evap_bs, remove_from_soil, hydraulic_redistribution

Implemented use of create_test_soillayers and set input arrays to pointers for consistency.

Updated array inputs to reflect pointer values, formatting updated

- addressing #218 (comment)

- folded tests for 1 and maximum number of soil layers into a loop
- defined 	`qty` (amount of soil moisture to be removed from soil by function` as fraction of `swc`
- added layer/test information if expectations fail

- defined tol3 and tol6 in `test/sw_teshelpers.h`
- converted all `EXPECT_NEAR(x, y, 0.0*1)` into `EXPECT_NEAR(x, y, tol*)` and similar cases
-> in general, we should use `tol6` except in known cases where the function produced floating point arithmetic issues: currently, `hydraulic_redistribution`

- according to https://github.com/DrylandEcology/DrylandEcologyProtocols/blob/master/C_Coding_Style.md#indentation-and-spacing-1
- added space between "for" and "(..."
- added space between ")" and "{"

- some expected values were incorrect, but masked by too lax tolerance values of 0.1 or 0.01
--> replaced tolerance values with `tol6` and fixed expected values

[albeit I continue to believe that hard-coding such expected values asks for trouble in the future if we were to change inputs or algorithms; instead, I believe that unit tests should test for general behavior, ranges, and physical consistency, as well as for edge cases]

- previously, names of water balance checks were not reported in unit tests
- this was because they were erased, but not re-initialized, for repeated simulation runs

--> use a global variable `SW_SoilWater.is_wbError_init` instead of a local static one `do_once` to initialize water balance checks

- previously, if there was no extractable water (no water or no coefficients), then arrays were returned untouched
--> problem, `qty` was not set to zero
--> fixed

- new unit tests that checks
* behavior under frozen soil layers
* makes sure that 0 <= sum of extracted quantity <= requested rate

- updated/corrected documentation of function

This reverts commit fb9f6c6.

This reverts commit fb9f6c6.

…_soil"

- EXPECT_LE(qty_sum, rate): appveyor-ci (but not travis-ci or my local tests) fail with  "Expected: (qty_sum) <= (rate), actual: 0.62 vs 0.62" (#218 (comment))
--> provide message with more details on numbers on failure

- EXPECT_LE(qty_sum, rate): appveyor-ci (but not travis-ci or my local tests) fails with "Expected: (qty_sum) <= (rate), actual: 0.62000... vs 0.62000..."

--> it almost appears as `EXPECT_LE` is behaving as `EXPECT_LT` on appveyor-ci in this case
--> hack: add `tol9` to `rate`

…17_Connor

Updated unit tests to loop through nlyrs = 1 &  nlyrs = 25. Updated formatting.

Reformatted and updated unit tests to utilize create_test_soillayers function and loop through min and max values for nlyrs.

- addressing #218 (review)

Addressing #266

This commit changes only comments, no changes to the code.

- "warning: Found unknown command `\inputs'"
--> change `@inputs` to `@param`

- "warning: Found unknown command `\params'"
--> change `@params` to `@param`

- "warning: Found unknown command `\parameters'"
--> change `@parameters` to `@param`

- "warning: Found unknown command `\sideeffects'"
--> change `@sideeffects` to `@sideeffect`

- "warning: Found unknown command `\references'"
--> change `@references` to `@see` and use doxygen autolink to generate https refs

- fix equations using doxygen tag \f$

- "warning: Illegal command \n as part of a title section"
--> fix `Doxygen` alias definition for `sideeffects`, i.e., added escaped `\"`

- "warning: Found unknown command `\f'"
--> change `@f` to use doxygen autolink to generate links to other source files

- "warning: found </sub> tag while expecting </superscript>" and
" warning: end of comment block while expecting command </superscript>"
--> remove `SUB` tags

--> hack to make documentation possible for objects defined under #ifdef ...
see https://stackoverflow.com/questions/54060666/documenting-conditional-exclusive-code-in-doxygen

- etc.
--> currently, there are no more warnings on my local system except those arising from README.md

Silly me: the correct preprocessor directive is `#undef` and not `#undefine`

- addressing #266 (doxygen warnings)

- this commit eliminates all remaining doxygen warnings, i.e., there are currently no more warnings: we should strive to keep it that way
--> `doxygen Doxyfile | grep warning` should return empty

- fixed outdated googleTest link
- formatted code so that it works both for github-markdown and doxygen-supported markdown

- added table of contents

- use implicit reference links where suitable to make text more readable

- fix commit 693cf5d

- close #265

- if successful this will finalize #266 (doxygen warnings)

- each travis-ci build step must be on it's own line starting with a `-`

- follow up to commit 41bc0da

- it may be that we need to install additional packages for doxygen to run successfully

- addressing #266

- in particular, fix the following warnings described in #266 (comment)
```
/home/travis/build/DrylandEcology/SOILWAT2/SW_Output_outarray.c:114: warning: argument 'SW_Model' of command @param is not found in the argument list of SW_OUT_set_nrow(void)
/home/travis/build/DrylandEcology/SOILWAT2/SW_Output_outarray.c:114: warning: argument 'Globals' of command @param is not found in the argument list of SW_OUT_set_nrow(void)
/home/travis/build/DrylandEcology/SOILWAT2/SW_Output_outarray.c:114: warning: argument 'use_OutPeriod' of command @param is not found in the argument list of SW_OUT_set_nrow(void)
```

- addressing #89 (Re-organize repository with more sub-folders)

…eptions)

- fix #266 (comment)
- addressing #266

- new script `tools/run_doxygen.sh`
- new make targets: "doc" and "doc_clean"

- continuous integration: travis-ci will now use the new script which fails on warnings, but disregards exceptions that are documented in the new file `doc/doxygen_exceptions.txt`

- currently, there is one known exception, see #267

- moved `Doxyfile` to `doc/` (addressing #89)

This works well locally, but travis-ci fails with
```
# Examine log file for remaining warnings/errors
warnings=$(grep "warning\|error" ${log})
grep "warning\|error" ${log}
makefile:260: recipe for target 'doc' failed
make: *** [doc] Error 1
The command "make doc" exited with 2.
```

It is not clear to me why `grep "warning\|error" ${log}` would exit with code 2. As an attempt, I catch grep's stderr and assign it to `warnings` as well.
It is also not clear whether or not travis-ci expects that this script (called by `make doc`) should define an exit value if we got warnings (see https://docs.travis-ci.com/user/job-lifecycle#how-does-this-work-or-why-you-should-not-use-exit-in-build-steps).

- previous commit 6f6a058 didn't work

- maybe travis-ci prefers extended (instead of basic) regular expressions? --> add `-E` option

- for goodness sake, we now search for case insensitive warnings/errors -> option `-i`

- previous commit 6f6a058 didn't work

- after installing and running travis locally, it seems that `grep` returns a non-zero exit status if nothing matches (i.e., we want nothing to match!)
--> use grep ... || echo "" instead

- this commit uses a wrong filename for doxygen exceptions, i.e., the `make doc` should fail on travis-ci because it will find doxygen warnings

- if indeed, travis-ci fails with this commit, then our continuous integration checks pass both positive and negative cases correctly

- commit 952e100 tested if travis-ci checks fail if `make doc` finds warnings:
it did find warnings and printed them to the output; however, it did not fail

--> add non-zero `exit` code to script if there are warnings

This reverts commit 952e100.

- link to latest doi release on zenodo
- remove github downloads (since it wasn't doing what we wanted it for)
- rename "Unix" badge to more appropriately "*nix"

- addressing #74 (Include detailed user manual in doxygen documentation)
- close #75 (Include detailed installation instructions in doxygen documentation)

- subpages for inputs and outputs are currently only place holders

- function `create_test_soillayers` can now use the fully fledged function `set_soillayers` (from commit "Merge branch 'feature_soillayerswap' into Bugfix_117_Connor") -- instead of the unit-test local and feature-incomplete `_set_layers`

- small fix to README concerning installation of clang via macports

- include input files verbatim
- this requires that the `doxyfile` "EXAMPLE_PATH" is set correctly

- clarified/expanded comments in input files for stand-alone use and for SOILWAT2 user manual
- added notes for users to highlight dependencies and forcing inputs vs. parameters

- improve clarity of user manual
- add output section