Updated documentation for setFullTime(long)

[BlameOmar]

setTime(long) is implemented using setFullTime(long). As long as the latter is not used to set the time to a point in the past, it should be as safe to use as the former. I'm uncertain as to what would happen if time were rewound, so I've adapted the advisory for that case.

[SagaciousZed]

This breaks the formatting conventions, please fix.

[BlameOmar]

I assume that I made a line too long. That's difficult to notice on the web interface; I'll make changes locally next time. I hope there are no other issues.

[Wolvereness]

I don't think this change is appropriate; the current phrasing is sufficient to warn about possible behavior. This additionally carries a burden of proof as to if it's actual safe; you're effectively changing a contract with this new documentation.

So, in light of a more detailed documentation / justification, retaining our current documentation would be a better decision.

It's also worth noting that the hesitation here is more toward the "you're doing something unsafe!" -> "Oh, it's perfectly fine", and I hope it doesn't discourage future discourse or contributions.

[BlameOmar]

The justification is in the implementation of setTime(long), which caries no such warning:

public void setTime(long time) {
        long margin = (time - getFullTime()) % 24000;
        if (margin < 0) margin += 24000;
        setFullTime(getFullTime() + margin);
}

setTime(long) calls setFullTime(long), passing the sum of a non-negative number an the current time as returned by getFullTime(). It follows that doing the same thing using setFullTime(long) directly would be at least as safe as calling setTime(long) multiple times in a loop as long as a number >= getFullTime() is passed.

As the only thing setFullTime(long) can do that setTime(long) ordinarily won't (the current implementation does not guard against overflow) is to "go back in time", which is what the warning should apply to.

I can amend the documentation to say something along the lines of "Take care to not set the time to a point in the past, or bad things may happen", which would better emphasize that using setFullTime(long) recklessly is potentially dangerous.