AstronomyUtils API is confusing / lacking javadoc

[William Bourque]

The apogy.core.environment package has the AstronomyUtils to get Sun/Moon information and to perform angle conversion. However, I find its API very confusing to use.

Currently, I don't think it is possible to use the API without looking at the source code. I don't think it should be required.

To illustrate, I will show the function getHorizontalSunPosition() as an example. However, note that most functions in AstronomyUtils suffers the same issues.

The getHorizontalSunPosition() methods takes 3 parameters. Using Eclipse auto-complete give the following: AstronomyUtils.INSTANCE.getHorizontalSunPosition(arg0, arg1, arg2)

Eclipse context help on those arguments only mentions type of the parameters, which are "Date arg0, double arg1, double arg2".

By looking at the source code of AstronomyUtils, we find that "arg0" is the "target date", while "arg1" is the "observer longitude" and "arg2" the "observer latitude".

It would been easier for the user if the parameters would be named as such or if a JavaDoc would be present to give this information.