Documentation can be much better

[paleolimbot]

We now have full doxygen output for the C API (link is currently broken)...this could be leveraged to make the documentation more useful (right now everything is grouped by convenience and few functions have their own documentation).

[paleolimbot]

I wonder if the whole doxygen output could be put into a roxygen templates directory so that we can do:

#' @template GEOSGeom_whatever

...and we get a @section on the C implementation.

[kylebutts]

I think I can help with this :-) Maybe I could start with a vignette or two?

[paleolimbot]

Looks like the C API docs are back up! https://libgeos.org/doxygen/geos__c_8h.html

I think the main thing I've been dreading doing is splitting up the catch-all man pages into individual functions. Basically, every function should have its own (although a few functions grouped together is OK, like for linear referencing).

A lot of the text can be copied from the C API docs (e.g., for distance: https://libgeos.org/doxygen/geos__c_8h.html#ab14339b938018c745572403f72660f57 ), but many of the descriptions there aren't complete. That said, including more complete documentation (e.g., with details of the algorithm) would be problematic to maintain since it changes for every release.

Happy to have whatever you feel like contributing! I do think that the "giving each function its own help page" bit is the most important though.