Javadoc of `SVGRasterizer` is incomplete or wrong

[laeubi]

I just noticed that the javadoc is probably incomplete or wrong when I reviewed another PR in that area:

eclipse.platform.swt/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/internal/image/SVGRasterizer.java

Lines 23 to 35 in 508ad4a

	public interface SVGRasterizer {
	/**
	* Rasterizes an SVG image from the provided {@code InputStream} using the
	* specified zoom.
	*
	* @param stream the SVG image as an {@link InputStream}.
	* @param zoom the scaling factor (in percent) e.g. {@code 200} for doubled
	* size. This value must be greater zero.
	* @return the {@link ImageData} for the rasterized image, or {@code null} if
	* the input is not a valid SVG file or cannot be processed.
	*/
	public ImageData rasterizeSVG(InputStream stream, int zoom) throws IOException;
	}

I see the following issues:

1. IOException is thrown but not documented under what condition this happens, the @return claims it return null on invalid data but why not throw IOException always it seems odd to have null here (then maybe Optional would have been a better choice) and what invalid means.
2. In the head it talks about a "zoom" (also parameter is named) but then in the description it says it is a scaling factor in percent, where a factor usually has no unit and percent itself is usually defined as 1% be a factor of 0.01 so for a scaling factor that represents the double size one would expect to have 2.0 as a factor.

For example, 45% (read as "forty-five percent") is equal to the fraction ⁠45/100⁠, or 0.45.

So I think the javadoc should be streamlined here to avoid confusion even if it is an internal API and only has one implementation at the moment.

[HeikoKlare]

• IOException is thrown but not documented under what condition this happens, the @return claims it return null on invalid data but why not throw IOException always it seems odd to have null here (then maybe Optional would have been a better choice) and what invalid means.

That exception specification just seems to be a leftover. Probably the error handling evolving while adapting the PR back then. No IOException can currently be thrown but actually in the only implementation an SWT error may be thrown if the SVG cannot be loaded and null will be returned when the SVG cannot be rasterized. It probably makes sense to streamline that and I have no strong opinion in which way to do it.

• In the head it talks about a "zoom" (also parameter is named) but then in the description it says it is a scaling factor in percent, where a factor usually has no unit and percent itself is usually defined as 1% be a factor of 0.01 so for a scaling factor that represents the double size one would expect to have 2.0 as a factor.

Well, the parameter name is consistent to what is used at other places in SWT. Those values are always in percent (100% == 1.0) and actually constitute a scaling factor (200% means the image will be at twice its original size). But feel free to remove the term "scaling factor" if you think its misleading.