Add (more) documentation to classes and methods

[wolfig]

The chartfx library is very feature-rich and performant. However, as developer-user I would benefit a lot if there was (more) documentation, at least on the method level. An example from the LabelledMarkerRenderer:

e.g. I guess that "enableVerticalMarker" can be used to render a vertical marker/line - but does it? The samples available here are instructive, but as well very sparse with comments. However, from a viewpoint of efficiency, method documentation available in the IDE would be very beneficial.

[wirew0rm]

I agree but actually helpful documentation is surprisingly hard to write and maintain and one has to be careful not to end up with "documentation" that just rehashes the function name ("Enables the Vertical Markers"). In Java(FX) this is even more annoying since most functionality has a ...Property(), set...() and get...() so if you enforce Javadoc, the code in your screenshot would stop to fit on a single screen, while not providing a lot of benefit, that's why we stopped adding javadoc by default and also removed a lot of unmaintained outdated documentation.

But I'm all for documentation that provides an actual benefit. The question is of course as always having the time to do that and finding the right level of required documentation which I find especially difficult at the time of writing code.

As for your concrete example, I think the Problem is more in the naming. First it should be plural and then it should probably be an "orientation" enum rather than separate bools for horizontal and vertical but of course that cannot be easily changed without breaking the API, so in that case Documentation would probably be the next best thing to make it easier to understand. In general though I think if you know what the renderer is doing, methods such as these should explain what they are doing even without documentation. Otherwise a lot of the documentation is duplicated from the class-level (which from a users perspective is not a problem -- as long as it can be properly maintained to stay consistent, which I'd say we lack the resources for).

So we will probably not have time to go through the code and add documentation everywhere, but feel free to ask questions that are suprising/difficult to grasp and that turns out to get a better explanation we can add it (Or feel free to add a PR documenting what you would have wished to be written there before digging).