[mapserver-dev] typedef struct versus struct in mapserver.h

[Seth G]

Hi Even,

The SWIG doc updates are scattered through several pull requests and wiki pages. I'll put these together into an RFC before making any further changes and I'll leave the typedefs alone. 

I was trying to avoid touching the header files, but the docstrings have to be next to the properties to force SWIG to attach them to the nodes. It will only be properties that require a docstring here, functions are all documented in the .i files. 
I did try an approach of setting the docstrings with a macro and inserting just the macro in the .h files, but this added an extra level of indirection, and would likely mean no properties available in MapScript would be kept updated. 

The advantage of the SWIG docstrings is they can then be read from the Python source and then Sphinx can take over allowing internal doc links, inclusion of text, images, examples on a class by class basis. 

I'll upload some sample output as part of the RFC. 

Seth

--
web:http://geographika.co.uk
twitter: @geographika


On Sun, May 24, 2020, at 10:56 PM, Even Rouault wrote:
> On dimanche 24 mai 2020 21:33:25 CEST Seth G wrote:

> > Hi all,

> >

> > While going through documenting the various objects available in MapScript I

> > notice some objects in mapserver.h are declared:

> >

> > typedef struct {

> > ..

> > } symbolSetObj;

> >

> > and some are declared:

> >

> > struct styleObj{

> > ...

> > }

> >

> > The former has the minor benefit the class can be documented by SWIG within

> > the struct, whereas the latter must be documented before it. Does anyone

> > know if there is a reason for the differences?

> >

> > It would be nice to have them using a consistent declaration but changing

> > classObj to the first style breaks the code (see branch at [1]) due to

> > redefinitions in the mapserver-api.h (which is the "public MapServer API"

> > as described on the mailing list post [2]). Maybe best to leave alone if

> > this API is used throughout other projects [3]? Or is there a way to easily

> > update the public API?

> 

> I don't think this public API is much used, if it used at all outside of MapServer, given that it looks to be only embryonic. That said, the intent was good, and having the opaque typedef in mapserver-api.h was a good principle. It doesn't look to me to be a big deal to have the doc for the struct to be before it. I find this even a bit cleaner / closer to Doxygen.

> 

> Speaking about that, having SWIG docstring in .h is a bit messy. Have you considered using Doxygen instead ? It looks from http://www.swig.org/Doc4.0/Doxygen.html that there might be a possibility to make SWIG extra from Doxygen, but I didn't try it. Sorry if this has been discussed before and I didn't catch up.

> 

> --

> Spatialys - Geospatial professional services

> http://www.spatialys.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20200525/146a708c/attachment.html>