[mapserver-dev] mapserver.h and SWIG

[Seth G]

Thanks for the feedback Steve.

How about the grouping in https://github.com/mapserver/mapserver/pull/6071/commits/bdf511a52b834715fc32c77e00173b842ca72b64 ?

%immutable;
%mutable;
non SWIG

I'll move the char *template; to the immutable section. 

SWIG is used to document all struct properties plus their types, and Sphinx then makes them linkable. 

Seth

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


On Wed, May 20, 2020, at 12:53 AM, Steve Lime wrote:
> Organic is a good word for it although there was some effort to group related properties so numlabels, labels and maxlabels were are next to one another. So this will scatter those a bit. Probably ok IMHO given the advantage keeping some docs close to the base structures. 
> 
> —Steve
> 
> On Tue, May 19, 2020 at 5:19 PM Seth G <sethg at geographika.co.uk> wrote:
>> Hi all,
>> 
>>  I've opened a new pull request at https://github.com/mapserver/mapserver/pull/6071 which adds docstrings for the classObj properties available in MapScript. These can then be used to generate automated API docs for MapScript using Sphinx. 
>> 
>>  When adding the docstrings it would seem to make sense to regroup the struct properties. 
>>  I'm unsure if there is currently a logical grouping or ordering, or if properties have been organically added over the years. 
>> 
>>  It would make sense while adding docstrings to reduce the number of SWIG guards, and regroup similar to below:
>> 
>>  struct classObj {
>> 
>>  #ifdef SWIG
>>  %immutable;
>>  #endif
>> 
>>  ..all SWIG immutable properties
>>  #ifdef SWIG
>>  %mutable;
>>  #endif
>> 
>>  .. all SWIG mutable properties
>> 
>>  #ifndef SWIG
>>  all non-SWIG properties
>>  #endif /* not SWIG */
>> 
>>  };
>> 
>>  Does anyone see any issues with this, or reservations in general to adding the docstrings?
>>  I've read through https://stackoverflow.com/questions/26818011/does-the-order-of-members-in-a-struct-matter but there are no array properties (at least for classObj).
>> 
>>  Regards,
>> 
>>  Seth
>> 
>>  --
>>  web:http://geographika.co.uk
>>  twitter: @geographika
>>  _______________________________________________
>>  mapserver-dev mailing list
>> mapserver-dev at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20200521/f1135f65/attachment.html>