[jfx18] RFR: 8279345: Realign class docs of LightBase and subclasses

[Ambarish Rapte]

On Tue, 25 Jan 2022 00:40:18 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> Now that the standard concrete light types were added, there is an opportunity to rearrange and rewrite some of the class docs. Here is a summary of the changes:
>> 
>> * Moved the explanations of attenuation and direction up to `LightBase` since different light types share characteristics. `LightBase` now contains a summary of its subtypes and all the explanations of the properties/characteristics of the lights divided into sections: Color, Scope, Direction, Attenuation.
>> * Each light type links to the relevant section in `LightBase` when it mentioned the properties it has.
>> * Added examples of real-world applications for each light type.
>> * Consolidated the writing style for all the subclasses.
>
> modules/javafx.graphics/src/main/java/javafx/scene/AmbientLight.java line 37:
> 
>> 35:  * <p>
>> 36:  * {@code AmbientLight}s can represent strong light sources in an enclosed area where the lights bounces from many
>> 37:  * objects, causing them to be illuminated from many directions. A strong light in a room and moonlight are common light
> 
>> A strong light in a room ...
> 
> I think this is OK, as long as a reader doesn't think of an overhead light in a room, which also has the properties of a point light.

Ambient light is a light that comes from all directions, scattered from different surfaces and it does not cast shadow. So I think the example of strong light and moon light should be avoided. Moon light is more like the Sun light, a directional light.

-------------

PR: https://git.openjdk.java.net/jfx/pull/717