Add docstrings and improve function naming

src/world/weather.jl

@@ -30,11 +30,23 @@ function Base.length(weather::Weather)
     return Dates.value(weather.lastdate - weather.firstdate) + 1
 end
 
+"""
+    daynumber(weather, date)
+
+Returns the number of days, counting `weather.firstdate` as day `1`.
+"""
 function daynumber(weather::Weather, date::Date)
     @assert weather.firstdate <= date <= weather.lastdate
     return Dates.value(date - weather.firstdate) + 1
 end
 
+"""
+    findspans(predicate_fn, array) -> Vector{Tuple{Int, Int}}
+
+Returns spans of indices in a 1-d `array` where a `predicate_fn`
+returns `true`.  The spans are returned as a `Vector{Tuple{Int,
+Int}}`, where each tuple is of the form `(start_index, end_index)`.
+"""
 function findspans(predicate_fn, arr::AbstractVector)
     spans = Tuple{Int, Int}[]
     startidx = nothing
@@ -54,10 +66,16 @@ function findspans(predicate_fn, arr::AbstractVector)
     return spans
 end
 
-function fix_missing_weatherdata!(df::DataFrame)
-    colnames_to_fix = ["min_temperature", "max_temperature", "mean_temperature",
-                       "precipitation", "potential_evapotranspiration"]
-    for colname in colnames_to_fix
+"""
+    check_missing_weatherdata(dataframe)
+
+Check the weather input data for missing values in columns where input
+values are required.
+"""
+function check_missing_weatherdata(df::DataFrame)
+    colnames = ["min_temperature", "max_temperature", "mean_temperature",
+                "precipitation", "potential_evapotranspiration"]
+    for colname in colnames
         spans = findspans(ismissing, getproperty(df, colname))
         # TODO: fix missing values and warn here instead of error
         if ! isempty(spans)
@@ -101,7 +119,7 @@ function initweather(weatherfile::String, startdate::Date, enddate::Date)
               * " expected $(Dates.value(enddate - startdate) + 1), got $(nrow(df)))."
               * " Missing dates are $(setdiff(startdate:enddate, df.date)).")
     end
-    fix_missing_weatherdata!(df)
+    check_missing_weatherdata(df)
     return Weather(; firstdate = minimum(df.date),
                    lastdate = maximum(df.date),
                    windspeed = df.mean_windspeed,