Improve Script API docs

[frosch123]

This PR includes #12372 as prerequisite.

Motivation / Problem

• Script API and Wallclock time #12339 asks for better API documentation about timekeeping.
• Various other parts of the docs needed improving too.

Description

• Add main pages to the AI/GS docs.
• Fix doxygen syntax errors and broken links.
• Complete and fix the game ID documentation.
• Document timekeeping and which method returns economy- or calendar-time.
  • The methods link to documentation sections "ScriptEconomyDate" and "ScriptCalendarDate". These can be turned into classes with the same name later.
• Replace C++ types with squirrel-like types in signatures:
  • char *, std::string, std::optional<std::string>, ... should all just be string in the API docs.
  • SQInteger, uint, int16_t, ... should all just be int in the API docs.

Limitations

Checklist for review

Some things are not automated, and forgotten often. This list is a reminder for the reviewers.

• The bug fix is important enough to be backported? (label: 'backport requested')
• This PR touches english.txt or translations? Check the guidelines
• This PR affects the save game format? (label 'savegame upgrade')
• This PR affects the GS/AI API? (label 'needs review: Script API')
  • ai_changelog.hpp, game_changelog.hpp need updating.
  • The compatibility wrappers (compat_*.nut) need updating.
• This PR affects the NewGRF API? (label 'needs review: NewGRF')
  • newgrf_debug_data.h may need updating.
  • PR must be added to API tracker

[2TallTyler]

@frosch123 Do you want to merge this? It's been approved for a minute. 😉

[PeterN]

Let's assume this is still good to go... and can be fixed if not.