lopcode
Fix tables in docs
Some of the libvips docs use unsupported table HTML, so they end up getting HTML escaped and look pretty ugly in the vips-ffm Javadoc. For example: https://vipsffm.photofox.app/app.photofox.vipsffm/app/photofox/vipsffm/VImage.html#buildlut(app.photofox.vipsffm.VipsOption...) (as of libvips 8.15.5)
Figure out what to do about these tables. Ideally they'd get turned in to valid Javadoc tables. But perhaps rendering as markdown and using @code would be enough.
Another idea - we could target Java 22 compatibility but use 23 source mode, and generate Markdown Javadoc comments instead
Hello, libvips 8.17 has switched to gi-docgen for doc formatting. Sample output:
https://www.libvips.org/API/8.17/
We get a working search function too (omg). It's all markdown (no html), with extra a little syntax for linking, seealso, and optional arguments.
Looks great! Appreciate the heads up, it's a good excuse to look at this again and get the docs all fixed up
@jcupitt I've started working on this today, so a quick question - for unreleased versions of libvips, I'll need to build my own libs from the source to link against for code generation (which is fine). Are you using tags on the libvips repo to track unreleased versions? For example, is this tag the latest for 8.17? https://github.com/libvips/libvips/tree/v8.17.0-test4
I would just build the head of master -- we have supported releases in stable branches.
Took more work than expected, but I think the effort was worth it.
I can't yet tell if it's safe to keep the target compatibility to Java 22 whilst having Java 23 source (required for Markdown comments). I'm currently feeling like it would be safer to raise the minimum supported JDK by one version to 23, which isn't so bad because 22 wasn't a "long term support" release anyway. I think the improved comments are worth it.
Before (rendered, with pre table hacks making table docs unusable):
After:
(Source)
(Rendered)