Docstring for ModelChainResult (#1233)

* see how this docstring works

* one long sentence

* progress

* complete draft

* adjustments

* correct use of tuple

* correct func and method references

* move _PerArray to module scope

* add dataclass docstring

* try _typehints

* remove _typehints

* remove class docstring, add a few See Also to pvsystem

* make public

Author: cwhanse

pvlib/modelchain.py

@@ -245,12 +245,15 @@ def get_orientation(strategy, **kwargs):
     return surface_tilt, surface_azimuth
 
 
+# Type for fields that vary between arrays
+T = TypeVar('T')
+
+
+PerArray = Union[T, Tuple[T, ...]]
+
+
 @dataclass
 class ModelChainResult:
-    _T = TypeVar('T')
-    PerArray = Union[_T, Tuple[_T, ...]]
-    """Type for fields that vary between arrays"""
-
     # these attributes are used in __setattr__ to determine the correct type.
     _singleton_tuples: bool = field(default=False)
     _per_array_fields = {'total_irrad', 'aoi', 'aoi_modifier',
@@ -260,27 +263,99 @@ class ModelChainResult:
 
     # system-level information
     solar_position: Optional[pd.DataFrame] = field(default=None)
+    """Solar position in a DataFrame containing columns ``'apparent_zenith'``,
+    ``'zenith'``, ``'apparent_elevation'``, ``'elevation'``, ``'azimuth'``
+    (all in degrees), with possibly other columns depending on the solar
+    position method; see :py:func:`~pvlib.solarposition.get_solarposition`
+    for details."""
+
     airmass: Optional[pd.DataFrame] = field(default=None)
+    """Air mass in a DataFrame containing columns ``'airmass_relative'``,
+    ``'airmass_absolute'`` (unitless); see
+    :py:meth:`~pvlib.location.Location.get_airmass` for details."""
+
     ac: Optional[pd.Series] = field(default=None)
+    """AC power from the PV system, in a Series [W]"""
+
     tracking: Optional[pd.DataFrame] = field(default=None)
+    """Orientation of modules on a single axis tracker, in a DataFrame with
+    columns ``'surface_tilt'``, ``'surface_azimuth'``, ``'aoi'``; see
+    :py:func:`~pvlib.tracking.singleaxis` for details.
+    """
+
+    losses: Optional[Union[pd.Series, float]] = field(default=None)
+    """Series containing DC loss as a fraction of total DC power, as
+    calculated by ``ModelChain.losses_model``.
+    """
 
     # per DC array information
     total_irrad: Optional[PerArray[pd.DataFrame]] = field(default=None)
+    """ DataFrame (or tuple of DataFrame, one for each array) containing
+    columns ``'poa_global'``, ``'poa_direct'`` ``'poa_diffuse'``,
+    ``poa_sky_diffuse'``, ``'poa_ground_diffuse'`` (W/m2); see
+    :py:func:`~pvlib.irradiance.get_total_irradiance` for details.
+    """
+
     aoi: Optional[PerArray[pd.Series]] = field(default=None)
+    """
+    Series (or tuple of Series, one for each array) containing angle of
+    incidence (degrees); see :py:func:`~pvlib.irradiance.aoi` for details.
+    """
+
     aoi_modifier: Optional[PerArray[Union[pd.Series, float]]] = \
         field(default=None)
+    """Series (or tuple of Series, one for each array) containing angle of
+    incidence modifier (unitless) calculated by ``ModelChain.aoi_model``,
+    which reduces direct irradiance for reflections;
+    see :py:meth:`~pvlib.pvsystem.PVSystem.get_iam` for details.
+    """
+
     spectral_modifier: Optional[PerArray[Union[pd.Series, float]]] = \
         field(default=None)
+    """Series (or tuple of Series, one for each array) containing spectral
+    modifier (unitless) calculated by ``ModelChain.spectral_model``, which
+    adjusts broadband plane-of-array irradiance for spectral content.
+    """
+
     cell_temperature: Optional[PerArray[pd.Series]] = field(default=None)
+    """Series (or tuple of Series, one for each array) containing cell
+    temperature (C).
+    """
+
     effective_irradiance: Optional[PerArray[pd.Series]] = field(default=None)
+    """Series (or tuple of Series, one for each array) containing effective
+    irradiance (W/m2) which is total plane-of-array irradiance adjusted for
+    reflections and spectral content.
+    """
+
     dc: Optional[PerArray[Union[pd.Series, pd.DataFrame]]] = \
         field(default=None)
+    """Series or DataFrame (or tuple of Series or DataFrame, one for
+    each array) containing DC power (W) for each array, calculated by
+    ``ModelChain.dc_model``.
+    """
+
     diode_params: Optional[PerArray[pd.DataFrame]] = field(default=None)
+    """DataFrame (or tuple of DataFrame, one for each array) containing diode
+    equation parameters (columns ``'I_L'``, ``'I_o'``, ``'R_s'``, ``'R_sh'``,
+    ``'nNsVth'``, present when ModelChain.dc_model is a single diode model;
+    see :py:func:`~pvlib.pvsystem.singlediode` for details.
+    """
+
     dc_ohmic_losses: Optional[PerArray[pd.Series]] = field(default=None)
-    losses: Optional[Union[pd.Series, float]] = field(default=None)
+    """Series (or tuple of Series, one for each array) containing DC ohmic
+    loss (W) calculated by ``ModelChain.dc_ohmic_model``.
+    """
 
+    # copies of input data, for user convenience
     weather: Optional[PerArray[pd.DataFrame]] = None
+    """DataFrame (or tuple of DataFrame, one for each array) contains a
+    copy of the input weather data.
+    """
+
     times: Optional[pd.DatetimeIndex] = None
+    """DatetimeIndex containing a copy of the index of the input weather data.
+    """
 
     def _result_type(self, value):
         """Coerce `value` to the correct type according to

pvlib/pvsystem.py

@@ -3074,6 +3074,10 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent,
     Rw: numeric
         Equivalent resistance [ohm]
 
+    See Also
+    --------
+    :py:func:`~pvlib.pvsystem.dc_ohmic_losses`
+
     References
     ----------
     .. [1] PVsyst 7 Help. "Array ohmic wiring loss".
@@ -3105,6 +3109,10 @@ def dc_ohmic_losses(resistance, current):
     loss: numeric
         Power Loss [W]
 
+    See Also
+    --------
+    :py:func:`~pvlib.pvsystem.dc_ohms_from_percent`
+
     References
     ----------
     .. [1] PVsyst 7 Help. "Array ohmic wiring loss".