Lua Documentation issues regarding messages

[kaputtnik]

I find it very hard to understand and have trouble to distinguish between messages for message boxes and messages which arrive in the inbox. Maybe i do not understand all that stuff, so please be patient with my words :-)

If possible at least the inbox related things should be renamed, e.g.:

Player:send_message() -> Player:send_notice()
Player.messages -> Player.notices
messages.lua:send_message() -> messages.lua:send_notice()
wl.Game.Message -> wl.Game.Notice

If renaming is too much work, it should be considered to clarify the descriptions of the functions, classes and property in that way that it is clear that those are only related to the inbox.

For message boxes there are 4 functions: 1 in wl.Game.Player and 3 in messages.lua. Those functions have some failures in the description:

https://wl.widelands.org/docs/wl/autogen_wl_game/#wl.game.Player.message_box
Here is a link to messages.lua:send_message() which is inbox related. So i guess this link is wrong? I do not understand why this function should be used carefully.

https://wl.widelands.org/docs/wl/autogen_auxiliary_messages/#message_box
The arguments 'message and 'parameters' are not explained much. By testing i found that at least this arguments must be passed in this way:

message_box(plr, "This is the title", p("This the message, or body"), {})

The message (or body) has to be in a p(), otherwise it isn't shown.
'parameters' must be at least an empty table, otherwise the game crashes.

https://wl.widelands.org/docs/wl/autogen_auxiliary_messages/#campaign_message_box
It says: "Sets message.h and message.w", i think this should be "Sets the width and height of the message box".
Message must be a table in form of {title = "The title", body = p("The body"),[opts]}. There should be an explanation of 'message' (which is not wl.Game.Message) somewhere so this can be linked.

https://wl.widelands.org/docs/wl/autogen_auxiliary_messages/#message_box_objective
It is unclear where one has to define obj_name, obj_title and obj_body.

Maybe we can omit some message box related functions?

[GunChleoc (gunchleoc)]

Migrated to https://github.com/widelands/widelands/issues/3254