It's time to update the script API documentation

[Yona-TYT]

As you may know, there have been some major changes to the scripts lately and some things in the documentation have become obsolete, so it needs to be updated as soon as possible.

The online documentation can be found at:

http://dwachs.github.io/simutrans-sqapi-doc/

Does anyone know or have access to this?.

[Andarix]

The documentation is probably created from the code with Doxygen.

And as far as I know, only Dwachs has access to it.

[Yona-TYT]

And as far as I know, only Dwachs has access to it.

I think he's been inactive for a while, so we're going to have problems.

[prissi]

In principle, this documentation is made automatically by adding proper comments when adding new functions. I can send him an email and ask him for the script to generate the documentations. Probably some comments have to be corrected again to include the new functions.

[Andarix]

https://github.com/simutrans/simutrans/tree/master/src/simutrans/script/api

files

Doxyfile_SQAPI
api_skeleton.cc

[Andarix]

The current version 1.12.0 of Doxygen gives the following error.

...
Parsing files
Preprocessing D:/simutrans_entwicklung/svn/simutrans_svn/trunk/src/simutrans/script/api/api_base.h...
Der Befehl "." ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
Parsing file D:/simutrans_entwicklung/svn/simutrans_svn/trunk/src/simutrans/script/api/api_base.h...
Preprocessing D:/simutrans_entwicklung/svn/simutrans_svn/trunk/src/simutrans/script/api/api_doc.h...
Der Befehl "." ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
...

Dwachs used Linux. I use Windows. I have no idea if that is the cause.

The list of api files itself is created.

[prissi]

It runs a shell script for parsing. Hence, it runs on the mingw command line after tweaking the directories.

[Andarix]

Simutrans-Squirrel-API_r11496.zip

[edit]

The documentation was incorrect.

[Yona-TYT]

Simutrans-Squirrel-API_r11496.zip

Is this ready to be used on github?, can I create a new branch for this.

[Andarix]

Is this ready to be used on github?, can I create a new branch for this.

Have you checked whether your changes are present and correct?

https://files.simutrans-germany.com/upload/Simutrans-Squirrel-API_r11504.zip

[prissi]

I think we should rather integrate into the build an update the documentation directly from the simutrans build. No need to fork this.

[Andarix]

Wiki - Squirrel Scripting - Simutrans Squirrel API

[Yona-TYT]

is_work_allowed_here() should be fixed,

It should be something like:

Code Select Expand

string is_work_allowed_here     (
        integer      pl,
        integer      tool_id,
        String        name or default_paramte
        coord3d      pos,
        table      tool
    )    
Also the rules:

Code Select Expand

static void forbid_way_tool (integer player_nr, integer tool_id, way_types wt, string default_paramter)
 
static void forbid_way_tool_rect (integer player_nr, integer tool_id, way_types wt, string default_paramter, coord pos_nw, coord pos_se, string err)
 
static void forbid_way_tool_cube (integer player_nr, integer tool_id, way_types wt, string default_paramter, coord3d pos_nw, coord3d pos_se, string err)
 

 
static void clear_forbid_way_tool (integer player_nr, integer tool_id, integer wt, string default_paramter)
 
static void clear_way_tool_rect (integer player_nr, integer tool_id, integer wt, string default_paramter, coord pos_nw, coord pos_se, bool allow)
 
static void clear_way_tool_cube (integer player_nr, integer tool_id, integer wt, string default_paramter, coord3d pos_nw, coord3d pos_se, bool allow)
 

 
static void clear_player (integer player_nr)
 
static void allow_way_tool_rect (integer player_nr, integer tool_id, way_types wt, string default_paramter, coord pos_nw, coord pos_se)
 
static void allow_way_tool_cube (integer player_nr, integer tool_id, way_types wt, string default_paramter, coord3d pos_nw, coord3d pos_se)

[Andarix]

api_skeleton.cc

line 224 - 249

[ceeac]

I think we should rather integrate into the build an update the documentation directly from the simutrans build. No need to fork this.

Implemented auto-generation of docs using CMake in r11540. The documentation is not built by default, but can be built using cmake --build <build dir> --target docs. The generated docs will be put in <build dir>/documentation/simutrans for the main program and <build dir>/documentation/sqapi for the script API.

[Yona-TYT]

Class to access tiles on the map.

There is the possibility to iterate through all objects on the tile:
local tile = tile_x( ... )
foreach(thing in tile) {
    ... // thing is an instance of the map_object_x (or a derived) class
}

This doesn't work currently, this patch fixes it: 0001-ADD-support-for-iterate-tile_x.patch

[prissi]

Thanks, in in r11562

[Yona-TYT]

This doesn't work currently, this patch fixes it: 0001-ADD-support-for-iterate-tile_x.patch

Unfortunately we need to revert this as it is affecting tile.get_objects()

Code Select Expand

          foreach(obj in t.get_objects()){
            local type = obj.get_type()
            t.find_object(type).unmark()
          }

This generates an error in the API, it seems that if it is used with get_objects() then you cannot directly use tile_x to iterate the objects.

And I don't know how to make both of them work without crashing.

[Isaac Eiland-Hall]

0001-ADD-support-for-iterate-tile_x.patch

Excuse me, but in the DSM-V it is no longer ADD but ADHD. Get it right!

[Yona-TYT]

Excuse me, but in the DSM-V it is no longer ADD but ADHD. Get it right!

[prissi]

reverted