irradiance.king documentation and output naming is wrong

[ramaroesilva]

Describe the bug

The King model is unclear and not even correct. Tbh, this is to be expected as the pvlib documentation irradiance.king explicitly assumes:

Note that this model is not well documented and has not been published in any fashion (as of January 2012).

The equation for King's model in PVPMC's webpage describes an isotropic transposition for both sky and ground diffuse assuming a zenith-dependent albedo. However, within pvlib the irradiance.king this is not made clear and it even mentions

"ground reflected irradiance is not included in this algorithm"

And while the output is poa_diffuse, it is identified as poa_sky_diffuse.

Expected behavior
Would propose that documentation and variable naming is corrected. Could also split the poa in sky and ground. @cwhanse proposed here that due to lack of proper documentation this function could be deprecated.

Would it be worth to include the ground diffuse implementation within irradiance.get_ground_diffuse?

Screenshots
Equation from PVPMC:

Versions:

• pvlib.__version__: 0.13.1

Additional context
Add any other context about the problem here.

[cwhanse]

The documentation mistake was made in the original port from Matlab. The Matlab code is clear that the function returns total POA diffuse.

[ramaroesilva]

Personally, I would focus this function in its ground diffuse part (it's its only differentiating element). Moreover, it is not coherent with the other transposition functions which, if I'm not mistaken, only cover the sky diffuse part (raising a problem for #2527).

If not, at least correct the docstring and variable naming.