INTERNAL vs public API confusion

[NightOwl888]

Hi, I am working on the C# port of spatial4j (Spatial4n) and could use some guidance about the publicly exposed APIs that are marked INTERNAL in the javadocs. The APIs in question are:

• JtsSpatialContext.makeShape(Geometry, boolean, boolean)
• JtsSpatialContext.makeShape(Geometry)
• BufferedLine
• BufferedLine.getLinePrimary()
• BufferedLine.getLinePerp()
• InfBufLine
• InfBufLine.distanceUnbuffered(Point)
• InfBufLine.quadrant(Point)

My question is: Are these APIs meant for public use, or aren't they?

While it seems that the message on InfBufLine is clear:

/**
 * INERNAL: A buffered line of infinite length.
 * Public for test access.
 */

BufferedLine is publicly documented for use, which contradicts the assumption that they should all be marked internal (similar to package-private). So, I suspect that not all of them should be treated the same.

I realize there may be some technical limitations I am unaware of that you are working around (marking them public so they can be tested), but in .NET we can easily test APIs that are marked internal. What I am after are whether they would ideally be package-private, or if they actually were intended for end users to be able to use.

[dsmiley]

Hi. BufferedLine's javadocs ought to remove the "INTERNAL" designation. Those two methods on JtsSpatialContext are good to be public but maybe "expert" or "advanced" designation. Someone creating their own classes to be used internally with JtsSpatialContext and other things in this package might want to call this.

[NightOwl888]

Perfect! That clears things up, thanks.