Add docstrings to all exported symbols

docs/src/api/public.md

@@ -34,6 +34,7 @@ Private = false
 ```@autodocs
 Modules = [PowerSystems]
 Pages   = ["outages.jl",
+           "contingencies.jl",
            "impedance_correction.jl",
            "plant_attribute.jl"
            ]
@@ -144,7 +145,8 @@ Filter  = t -> !(t isa AbstractString) && nameof(t) in names(PowerSystems) && ge
 
 ```@autodocs
 Modules = [PowerSystems]
-Pages   = ["supplemental_accessors.jl"]
+Pages   = ["supplemental_accessors.jl",
+           "supplemental_setters.jl"]
 Public = true
 Private = false
 ```
@@ -166,7 +168,8 @@ Pages = ["parsers/power_system_table_data.jl",
          "parsers/power_models_data.jl",
          "parsers/TAMU_data.jl",
          "parsers/psse_dynamic_data.jl",
-         "parsers/pm_io/common.jl"]
+         "parsers/pm_io/common.jl",
+         "parsers/im_io/matlab.jl"]
 Public = true
 Private = false
 Filter = t -> t ∉ [System]

src/PowerSystems.jl

@@ -789,7 +789,15 @@ abstract type Component <: IS.InfrastructureSystemsComponent end
 """ Supertype for "devices" (bus, line, etc.) """
 abstract type Device <: Component end
 
+"""
+All PowerSystems [Device](@ref) types support time series. This can be overridden for 
+custom component types that do not support time series.
+"""
 supports_time_series(::Device) = true
+"""
+All PowerSystems [Device](@ref) types support supplemental attributes. This can be overridden for 
+custom component types that do not support supplemental attributes.
+"""
 supports_supplemental_attributes(::Device) = true
 
 # Include utilities

src/base.jl

@@ -1158,6 +1158,11 @@ function remove_components!(::Type{T}, sys::System) where {T <: Component}
     return remove_components!(sys, T)
 end
 
+"""
+Remove all components of type `T` from the system.
+
+Throws `ArgumentError` if the type is not stored.
+"""
 function remove_components!(sys::System, ::Type{T}) where {T <: Component}
     components = IS.remove_components!(T, sys.data)
     for component in components
@@ -1166,6 +1171,9 @@ function remove_components!(sys::System, ::Type{T}) where {T <: Component}
     return components
 end
 
+"""
+Remove all components of type `T` that match `filter_func` from the system.
+"""
 function remove_components!(
     filter_func::Function,
     sys::System,
@@ -1409,6 +1417,10 @@ function get_contributing_devices(sys::System, service::TransmissionInterface)
     return [x for x in get_components(Branch, sys) if has_service(x, service)]
 end
 
+"""
+Container associating a [`Service`](@ref) with the [`Device`](@ref) components that
+contribute to it.
+"""
 struct ServiceContributingDevices
     service::Service
     contributing_devices::Vector{Device}
@@ -1510,6 +1522,10 @@ function get_connected_tail_reservoirs(sys::System, turbine::T) where {T <: Hydr
     ]
 end
 
+"""
+Container associating a hydro turbine with its connected [`Device`](@ref) components
+(e.g., [`HydroReservoir`](@ref) units).
+"""
 struct TurbineConnectedDevices
     turbine::HydroUnit
     connected_devices::Vector{Device}
@@ -2279,6 +2295,12 @@ function check_component(sys::System, component::Component)
     return
 end
 
+"""
+Check that all AC transmission [`Line`](@ref) and [`MonitoredLine`](@ref) components
+have valid rate values relative to the system base power.
+
+Returns `true` if all values are valid, `false` otherwise.
+"""
 function check_ac_transmission_rate_values(sys::System)
     is_valid = true
     base_power = get_base_power(sys)
@@ -2291,6 +2313,11 @@ function check_ac_transmission_rate_values(sys::System)
     return is_valid
 end
 
+"""
+Serialize a [System](@ref) instance. Returns a `Dict{String, Any}` 
+of the form `Dict("data_format_version" => "1.0", "field1" => serialize(sys.field1), ...)`,
+which can then be written to a JSON3 file.
+"""
 function IS.serialize(sys::T) where {T <: System}
     data = Dict{String, Any}()
     data["data_format_version"] = DATA_FORMAT_VERSION
@@ -2306,6 +2333,9 @@ function IS.serialize(sys::T) where {T <: System}
     return data
 end
 
+"""
+Deserialize a [System](@ref) instance from a JSON3 file; the reverse of [`IS.serialize`](@ref).
+"""
 function IS.deserialize(
     ::Type{System},
     filename::AbstractString;

src/contingencies.jl

@@ -1 +1,7 @@
+"""
+Supertype for contingency events that can be attached to components as supplemental
+attributes.
+
+Concrete subtypes include [`Outage`](@ref) and its descendants.
+"""
 abstract type Contingency <: SupplementalAttribute end

src/definitions.jl

@@ -455,6 +455,15 @@ Notes
 
 IS.@scoped_enum(StateTypes, Differential = 1, Algebraic = 2, Hybrid = 3,)
 
+@doc """
+Categorization of dynamic state variables.
+
+# Values
+- `Differential`: State governed by a differential equation
+- `Algebraic`: State governed by an algebraic constraint
+- `Hybrid`: State with both differential and algebraic aspects
+""" StateTypes
+
 IS.@scoped_enum(
     ReservoirDataType,
     USABLE_VOLUME = 1,
@@ -539,6 +548,17 @@ IS.@scoped_enum(
     Other = 5,
 )
 
+@doc """
+Configuration types for combined cycle power plants.
+
+# Values
+- `SingleShaftCombustionSteam`: Single-shaft arrangement with one combustion and one steam turbine
+- `SeparateShaftCombustionSteam`: Separate shafts for combustion and steam turbines
+- `DoubleCombustionOneSteam`: Two combustion turbines feeding one steam turbine
+- `TripleCombustionOneSteam`: Three combustion turbines feeding one steam turbine
+- `Other`: Other combined cycle configuration
+""" CombinedCycleConfiguration
+
 const PS_MAX_LOG = parse(Int, get(ENV, "PS_MAX_LOG", "50"))
 const DEFAULT_BASE_MVA = 100.0
 

src/models/cost_functions/MarketBidCost.jl

@@ -104,7 +104,7 @@ MarketBidCost(
         ancillary_service_offers,
     )
 
-# Constructor for demo purposes; non-functional.
+# Constructor that sets the startup cost to a small constant and the rest to 0.0.
 function MarketBidCost(::Nothing)
     MarketBidCost(;
         no_load_cost = nothing,
@@ -202,9 +202,10 @@ function set_start_up!(value::MarketBidCost, val::Real)
     set_start_up!(value, start_up_multi)
 end
 
-# Each market bid curve (the elements that make up the incremental and decremental offer
-# curves in MarketBidCost) is a CostCurve{PiecewiseIncrementalCurve} with NaN initial input
-# and first x-coordinate
+"""
+Return `true` if the given [`ProductionVariableCostCurve`](@ref) is a market bid curve
+(a `CostCurve{PiecewiseIncrementalCurve}` as used in [`MarketBidCost`](@ref)).
+"""
 function is_market_bid_curve(curve::ProductionVariableCostCurve)
     return (curve isa CostCurve{PiecewiseIncrementalCurve})
 end

src/models/dynamic_generator.jl

@@ -134,10 +134,15 @@ get_name(device::DynamicGenerator) = device.name
 get_states(device::DynamicGenerator) = device.states
 get_n_states(device::DynamicGenerator) = device.n_states
 get_ω_ref(device::DynamicGenerator) = device.ω_ref
+"""Get the [`Machine`](@ref) component of a [`DynamicGenerator`](@ref)."""
 get_machine(device::DynamicGenerator) = device.machine
+"""Get the [`Shaft`](@ref) component of a [`DynamicGenerator`](@ref)."""
 get_shaft(device::DynamicGenerator) = device.shaft
+"""Get the [`AVR`](@ref) component of a [`DynamicGenerator`](@ref)."""
 get_avr(device::DynamicGenerator) = device.avr
+"""Get the [`TurbineGov`](@ref) (prime mover) component of a [`DynamicGenerator`](@ref)."""
 get_prime_mover(device::DynamicGenerator) = device.prime_mover
+"""Get the [`PSS`](@ref) component of a [`DynamicGenerator`](@ref)."""
 get_pss(device::DynamicGenerator) = device.pss
 get_base_power(device::DynamicGenerator) = device.base_power
 get_ext(device::DynamicGenerator) = device.ext
@@ -175,6 +180,9 @@ function get_degov1_states(droop_flag::Int)
     end
 end
 
+"""
+Get the frequency droop parameter from the prime mover of a [`DynamicGenerator`](@ref).
+"""
 function get_frequency_droop(dyn_gen::DynamicGenerator)
     return get_frequency_droop(get_prime_mover(dyn_gen))
 end

src/models/dynamic_generator_components.jl

@@ -1,8 +1,49 @@
 abstract type DynamicGeneratorComponent <: DynamicComponent end
+
+"""
+Supertype for all Automatic Voltage Regulator (AVR) models for
+[`DynamicGenerator`](@ref) components.
+
+Concrete subtypes include [`AVRFixed`](@ref), [`AVRSimple`](@ref), [`AVRTypeI`](@ref),
+[`AVRTypeII`](@ref), [`IEEET1`](@ref), [`ESDC1A`](@ref), [`ESAC1A`](@ref),
+[`SEXS`](@ref), [`SCRX`](@ref), and others.
+"""
 abstract type AVR <: DynamicGeneratorComponent end
+
+"""
+Supertype for all synchronous machine models for [`DynamicGenerator`](@ref) components.
+
+Concrete subtypes include [`BaseMachine`](@ref), [`OneDOneQMachine`](@ref),
+[`SauerPaiMachine`](@ref), [`MarconatoMachine`](@ref), [`RoundRotorMachine`](@ref),
+[`SalientPoleMachine`](@ref), [`AndersonFouadMachine`](@ref), [`FullMachine`](@ref),
+and others.
+"""
 abstract type Machine <: DynamicGeneratorComponent end
+
+"""
+Supertype for all Power System Stabilizer (PSS) models for
+[`DynamicGenerator`](@ref) components.
+
+Concrete subtypes include [`PSSFixed`](@ref), [`PSSSimple`](@ref), [`IEEEST`](@ref),
+[`PSS2A`](@ref), [`PSS2B`](@ref), [`PSS2C`](@ref), [`STAB1`](@ref), and [`CSVGN1`](@ref).
+"""
 abstract type PSS <: DynamicGeneratorComponent end
+
+"""
+Supertype for all shaft and rotor models for [`DynamicGenerator`](@ref) components.
+
+Concrete subtypes include [`SingleMass`](@ref) and [`FiveMassShaft`](@ref).
+"""
 abstract type Shaft <: DynamicGeneratorComponent end
+
+"""
+Supertype for all turbine governor models for [`DynamicGenerator`](@ref) components.
+
+Concrete subtypes include [`TGFixed`](@ref), [`TGTypeI`](@ref), [`TGTypeII`](@ref),
+[`GasTG`](@ref), [`GeneralGovModel`](@ref), [`HydroTurbineGov`](@ref),
+[`IEEETurbineGov1`](@ref), [`SteamTurbineGov1`](@ref), [`DEGOV`](@ref),
+[`DEGOV1`](@ref), and others.
+"""
 abstract type TurbineGov <: DynamicGeneratorComponent end
 
 """

src/models/dynamic_inverter.jl

@@ -232,11 +232,17 @@ get_ω_ref(device::DynamicInverter) = device.ω_ref
 get_ext(device::DynamicInverter) = device.ext
 get_states(device::DynamicInverter) = device.states
 get_n_states(device::DynamicInverter) = device.n_states
+"""Get the [`Converter`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_converter(device::DynamicInverter) = device.converter
+"""Get the [`OuterControl`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_outer_control(device::DynamicInverter) = device.outer_control
+"""Get the [`InnerControl`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_inner_control(device::DynamicInverter) = device.inner_control
+"""Get the [`DCSource`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_dc_source(device::DynamicInverter) = device.dc_source
+"""Get the [`FrequencyEstimator`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_freq_estimator(device::DynamicInverter) = device.freq_estimator
+"""Get the [`Filter`](@ref) component of a [`DynamicInverter`](@ref)."""
 get_filter(device::DynamicInverter) = device.filter
 get_limiter(device::DynamicInverter) = device.limiter
 get_base_power(device::DynamicInverter) = device.base_power

src/models/dynamic_inverter_components.jl

@@ -1,9 +1,55 @@
 abstract type DynamicInverterComponent <: DynamicComponent end
+
+"""
+Supertype for all power electronic converter models for
+[`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`AverageConverter`](@ref),
+[`RenewableEnergyConverterTypeA`](@ref), and
+[`RenewableEnergyVoltageConverterTypeA`](@ref).
+"""
 abstract type Converter <: DynamicInverterComponent end
+
+"""
+Supertype for all DC source models for [`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`FixedDCSource`](@ref) and [`ZeroOrderBESS`](@ref).
+"""
 abstract type DCSource <: DynamicInverterComponent end
+
+"""
+Supertype for all output filter models for [`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`LCLFilter`](@ref), [`LCFilter`](@ref), and [`RLFilter`](@ref).
+"""
 abstract type Filter <: DynamicInverterComponent end
+
+"""
+Supertype for all frequency estimator models for
+[`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`KauraPLL`](@ref), [`ReducedOrderPLL`](@ref), and
+[`FixedFrequency`](@ref).
+"""
 abstract type FrequencyEstimator <: DynamicInverterComponent end
+
+"""
+Supertype for all inner control loop models for
+[`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`VoltageModeControl`](@ref), [`CurrentModeControl`](@ref),
+and [`RECurrentControlB`](@ref).
+"""
 abstract type InnerControl <: DynamicInverterComponent end
+
+"""
+Supertype for all output current limiter models for
+[`DynamicInverter`](@ref) components.
+
+Concrete subtypes include [`MagnitudeOutputCurrentLimiter`](@ref),
+[`InstantaneousOutputCurrentLimiter`](@ref), [`PriorityOutputCurrentLimiter`](@ref),
+[`SaturationOutputCurrentLimiter`](@ref), and [`HybridOutputCurrentLimiter`](@ref).
+"""
 abstract type OutputCurrentLimiter <: DynamicInverterComponent end
 
 abstract type ActivePowerControl <: DeviceParameter end

src/models/reserves.jl

@@ -34,11 +34,28 @@ reserves, respectively.
 A [`Reserve`](@ref) can be specified as a `ReserveSymmetric` when it is defined.
 """
 abstract type ReserveSymmetric <: ReserveDirection end
+
+"""
+Supertype for all reserve products, both spinning and non-spinning.
+
+Concrete subtypes include [`Reserve`](@ref) (parameterized by [`ReserveDirection`](@ref))
+and [`ReserveNonSpinning`](@ref).
+"""
 abstract type AbstractReserve <: Service end
 
 """
 A reserve product to be able to respond to unexpected disturbances,
 such as the sudden loss of a transmission line or generator.
 """
 abstract type Reserve{T <: ReserveDirection} <: AbstractReserve end
+
+"""
+Supertype for non-spinning (quick-start) reserve products.
+
+Non-spinning reserves can be brought online within a short time but are not
+currently synchronized to the grid. See also [`Reserve`](@ref) for spinning reserves.
+
+Concrete subtypes include [`ConstantReserveNonSpinning`](@ref) and
+[`VariableReserveNonSpinning`](@ref).
+"""
 abstract type ReserveNonSpinning <: AbstractReserve end

src/models/services.jl

@@ -8,5 +8,14 @@ such as the sudden loss of a transmission line or generator.
 """
 abstract type Service <: Component end
 
+"""
+All PowerSystems [Service](@ref) types support time series. This can be overridden for custom 
+types that do not support time series.
+"""
 supports_time_series(::Service) = true
+
+"""
+All PowerSystems [Service](@ref) types support supplemental attributes. This can be overridden for 
+custom service types that do not support supplemental attributes.
+"""
 supports_supplemental_attributes(::Service) = true

src/models/supplemental_setters.jl

@@ -1,8 +1,14 @@
+"""
+Set a single upstream turbine for a [`HydroReservoir`](@ref).
+"""
 function set_upstream_turbine!(reservoir::HydroReservoir, turbine::HydroUnit)
     set_upstream_turbines!(reservoir, [turbine])
     return
 end
 
+"""
+Set a single downstream turbine for a [`HydroReservoir`](@ref).
+"""
 function set_downstream_turbine!(reservoir::HydroReservoir, turbine::HydroUnit)
     set_downstream_turbines!(reservoir, [turbine])
     return