Some parts of documented C++ API do not available for public usage

[dron]

There are number of header files not being installed system wide hence are not available to user but still being documented. E.g., there are many files under the headers/geos/algorithm marked as non-installable. I think that they should be also excluded from the public API documentation, otherwise it is not possible to understand which parts of API are for public use and which are internal.

Best regards, Andrey

[mloskot]

---

Subject: Re: [Fwd: [geos-devel] Ticket #184] Date: Tue, 6 May 2008 23:26:18 +0200 From: Sandro Santilli <strk@…> To: Mateusz Loskot <mateusz@…> References: <4820B90C.5080207@…>

On Tue, May 06, 2008 at 10:01:16PM +0200, Mateusz Loskot wrote:

Hi Sandro, Sorry I'm bothering you, but could you give me some comments to this issue below? As I see, you have intentionally removed them:  http://trac.osgeo.org/geos/changeset/1600 Is it to separate public API from private/implementation headers?

Yes, I was sick of breaking API whenever there was a need to fix a design issue (many many times). I voted myself to only maintain the C-API finally... Dunno what the current idea is, but for sure I think GEOS api is far too wide to maintain.

-- strk

[mloskot]

Folks,

Any ideas and suggestions how should we handle this issue? Please, see Andrey's report and Sandro's explanation above and let's brainstorm some solution for this.

[pramsey]

Andrey and others need to tell us whether they mind having the API change more than they mind missing the public headers.

[strk]

The main page of doxygen documentation is clear on the matter. It reccommends using the C api and warns about troubles with the C++ one. Dox not not mentioning what's possible to use is part of the trouble. See:  http://download.osgeo.org/geos/doxygen/

An easy "fix" could be skipping the not-installed headers, but I find it useful for internal development to have doxygen documentation for internal classes, so I'd rather have some information added to class documentation as for whether the class is accessible trough the public interface.

[strk]

Easier fix committed in r2557 (installed all headers).