search

FLWL / aoe2-ai-module

Library to extend AI scripting capabilities in Age of Empires 2.
GNU Lesser General Public License v2.1
16 stars 6 forks source link

Missing documentation for facts and actions #2

Open FLWL opened 3 years ago

FLWL commented 3 years ago

Currently most facts, actions and their parameters are undocumented in the proto files. Adding documentation there would automatically carry over to the project's Wiki, creating a helpful reference, especially for more obscure functions.

01010100b commented 3 years ago

There already exists an excellent documentation source here: https://airef.github.io/index.html which could probably be used instead.

FLWL commented 3 years ago

That is indeed an excellent source of information and would be a waste of resources to duplicate. Although having to do some cross-referencing it should work fairly well for coding with this API. It could use some contributions regarding DE commands.

A few cases that I think should still be documented here: 1) Any custom actions and facts that are added by AI Module. Currently there's just "Goals", but in the future I can see "StrategicNumbers" and a few more being added. 2) The AI Module might support AoC at some point. The user looking at the API should assume that unless explicitly stated, a function will work on both DE and AoC. A notice should be added to facts and actions that are available only on one or the other.

As for the rest of the facts and actions, documenting them is certainly a very low priority task. Also no more than 1 sentence per message or parameter. Reasons for doing it at all might be for the completeness of the API (seems odd to have only some RPC messages documented) and to eliminate any guesswork regarding return values and parameters (the module modifies how some facts return values, plus there are parameter naming discrepancies compared to airef, it should be fairly obvious though). To alleviate the latter issue, there's also the option to standardize parameter names to airef as much as possible.

FLWL commented 3 years ago

In commit 8c54ee74320da5a491b2a9b6993699fd1ba784ee fact and action parameters were renamed to be more consistent and similar to airef.