Proposal: Enhance common-api with documentation

[Teiresias]

I have just started developing a more advanced(?) attack/defense system for AI bots. I feel the current common-api a bit hard to use: For example, in entity.js the definitions of entity and -templates are lined up one after another, with member functions not sorted. I (have to?) scroll through the whole file when searching for some entity property.

So, i got the idea of improving. I have used JsDoc with satisfying results for documenting JavaScript code and applied it to a patched version of the common-api to get a doxygen-like representation.

The tool is Apache-licensed, runs on (at least) Windows, Linux, BSD, and is highly customizable on the generated document format (see attachment description below). It should be possible to find or build a layout to fit nicely into the current 0AD documentation.

Question: Is there any interest in "officializing" this approach, and to adapt the whole common-api for generated html-docs as in the attachment documentation-proposal.zip? Any comments welcome.

The zip archive contains the following sub-sections:

• /common-api.original: The original common-api files for reference

• /common-api.jsdoc-compatible: A patched version. JsDoc does not accept the new Map-compatible JS loop style used in the EntityCollections. The module can be run within 0AD but i introduced some bugs (petra is training entities but does not gather/build at the moment).
• /common-api.documented: The patched version with documentation added.
• /default-layout: The JsDoc output via the default JsDoc template
• /special-layout: The JsDoc output via the template i use for my AI experiments/documentation (based on an elder JsDoc version). A sample on customizing documentation. I can provide the template if desired.

Notes:

1. I have not adapted all parts of the common-api to not waste much efforts if this proposal is rejected. The description of the "EntityCollection" class gives a good idea on how the results may look like.
2. As far as i know, Doxygen does not support JavaScript as an input language. There is a perl script which can convert JS sources into Doxygen-compatible C++. To me, this seems to much "make-do/Rube-Goldberg" style.

[agentx]

I don't know how many people work on the common api. If I had to guess, I'd say less than a hand full and once you got the quirks right, a documentation is not needed. So, I'm more in favor of documenting the quirks properly by hand than an automated documentation, because it would help to design a new bot api.

But even that is far less interesting than an advanced attack/defense system useable as a plugin for bots...

Edited December 28, 2014 by agentx

[Teiresias]

My idea is more of an API documentation/reference for the "customers" of the common-api (the bot writers) than the API designers. I got into 0AD AI programming by modifying testbot, which was a rather simple construction. With the AIs getting more and more advanced and the API following, i see the barrier for newcomers to raise. In my humble opinion, at least some parts of the common-api out-/bot-side interface require some degree of reverse-engineering to understand. I recall you saying "the hurdles to start with an AI are currently quite high".

If this keeps on going, it might result in new people becoming more and more scared off because the interface feels overwhelming and "unfriendly".

Besides, your second-last sentence "because it would help to design a new bot api" looks very interesting. Do you mean you'd prefer to discard the current bot/common-api system alltogether and re-start with a better design?

[agentx]

> the hurdles...

And there are more to manage after start Currently I think the most time consuming thing is late game debugging. A remote debugger to inspect and change variables would speed up development by magnitudes. Actually writing code, wrapping variables with print(), starting the game and starring at the console feels like web development 15 years ago. I think developers are attracted by IDE's, too.

[Teiresias]

Regarding the late game debugging, that's why i am using test suites so to catch at least the obvious faults before starting up a game. Currently i am just using Jasmine tests; but i am afraid for developing an attack/defense system i will have to build up a collection of system tests. This would mean specially designed maps with entities positioned to trip a particular behavior. Seems like a new real can of worms waiting for the tin-opener... But this is going off-topic.

I still believe in future, the hurdles mentioned combined with "level of profession" of the then-already-existant AI(s) may limit the number of newcomers in this area more and more.

[agentx]

> specially designed maps with entities positioned

I've stopped that, because I lost overview facing a packed map folder and switched to generating maps on the fly. Have a look at mainland.js or what I did to it https://github.com/agentx-cgn/Hannibal/blob/master/maps/random/brainland.js It only takes around 0.1 secs to create a map like this.

> may limit the number of newcomers in this area more and more.

I think most players have lots of ideas to improve AIs. There is probably a whole range of ideas, starting with "too many idle units", or "no point in attacking building X" up to "you did that already three times and never succeeded". It should be possible to try out new ideas without coding bots from scratch.

[mimo]

I've not understood what is the compatibility problem that you mention in your original post ? could you give more details, I thought it was just a documentation tool ?

If it has JS compatibility issues which prevent us from using some JS features that we would want to use, that's a very strong point against its use.

[Teiresias]

@agentx:
Trying out new ideas will still require knowledge of

• how to "read the game state/templates" and control the AI player's actions
• how to fit in your idea into the current structure of the bot. For example, if you are preparing for an early mass attack with multiple barracks continually training, how to pre-set the economy to provide resources in-time.

One can figure out all of this by just reading the sources, but it's probably becoming a challenge.

@mimo:
The compatibility issue is that JsDoc at the moment does not accept the following for-loop style:

for (let id of data.ents) for (let [id, ent] of this._entities)

I assume this is a new JS language feature introduced too recently for JsDoc to be already updated. At least, neither me nor any of my JS books knew of that style . If this is a problem, i may try and create a patch so the tool will accept that construct. Currently JsDoc reports a syntax error on these loops while parsing the sources.

At two other points i went for a quick cut:

1. Rewrote the API3.Template definition to not use the API3.Class({ ... }) constructor - it seems being phased out anyway.
2. Removed the surrounding anonymous function constructs var API3 = function () { ... }(API3); from the source as they seem to have no effect but encomplicate namespace detection. I presume they are intended for closuring up global variables, but i have not seen any.

At these two points, JsDoc accepts the source in its original shape but documenting it without these constructs was easier

[agentx]

Good thing jsdoc doesn't document for ... of, slowest loop ever.

[Teiresias]

I digged a little deeper. Apparently, JsDoc uses a separate parser for reading .js files - currently, Rhino and Esprima can be used. None of them seems to support the for-of loop construct. With the Mozilla people marking these as experimental, the other JS parser/runtime implementors seem to wait on how the experiment turns out.

It might be possible to patch Esprima's parseForStatement() function to accept the new style. I haven't checked that road: Judging by the results of this thread, noone is interested in a (Doxygen-like-)documentation of the bot API. Maybe the intended audience simply does not exist(?).

So, i consider my proposal to be rejected.

[feneur]

Maybe the intended audience simply does not exist(?).

I would guess that the people who would be mostly interested in this are not even aware of the possibility for them to code AIs for the game. The more skilled programmers can probably find things out on their own, but the others might not even know about the game at the moment. More documentation is usually better (as long as it's not giving the end result of more outdated documentation of course), so I think it might be a good thing in the long run. It's not something that's very likely to get a lot of people enthusiastic in the short run though. So I encourage you to not give up just yet

[niektb]

I must say that the hurdle to develop a new AI has been proved too high for me in the past. I actually landed in this forum a while ago with the intention to develop a new AI (you know, I had created a AoK AI but wanted to have more freedom). With that in mind I encourage every attempt to ease the road for newcomers (although it is unlikely that I would eventually develop a fully fledged AI myself considering my other tasks around here and the amount of time I have available) so that they don't strand before having something that works.

[mimo]

niektb: i think the problem is in your sentence "to develop a new AI" which is certainly a several years long program, I've seen on this forum a lot of people wanting to create their own ai from scratch, without being aware of what it means, and which have disappeared. But there are still other ways as to help and improve the existing ai, or even to fork it, which is much more manageable and I think more rewarding as you can see its effects in game quite rapidly.

teiresias: I would be happy with a pure documentation tool, but this one has to interpret the code which gives compatibility issues, and this is for me a real concern.

[niektb]

Mimo: unfortunately Aegis was difficult too. I was trying to start with something more simplistic but I already struggled with basic tasks like training and building. Simply because I did not know where to look (and Aegis didn't help me much further with its fancy planning system)

[mimo]

yep improving the petra doc is in my plans, but I never find the time to do it

[agentx]

I've completely underestimated the time it takes to create a framework for a bot. E.g, the economy, which fires commands like train, build, research towards the engine has been rewritten already three times. I've seen recently I wrote the first line of code last February, so, to sum up, I think I spend one month to understand API and Aegis, three to research the things I like to improve and now iterate for 6 months the framework to make the group scripts run on top. I don't know whether a documentation would have cut a lot from the first month, once it clicked that entity ids + tech template names is basically all what's needed to talk to the engine, I'd made progress very fast.

I've also thought of publishing here a minimal bot, which trains 1 unit, builds 1 house, researches 1 tech and runs on a given map with everything hard coded. This sounds like a 20 lines of code project and it actually is. However, to make that bot run on *any* map the next hurdle then is making the location of the building soft coded and you are knee deep in map analysis. And that is not trivial at all. I've started a wiki page about: https://github.com/agentx-cgn/Hannibal/wiki/Map-Analysis

In short, I think it makes sense to lower the hurdles at the beginning, but after the first month there are still some very huge roadblocks and after that you fight with your own code and are alone anyway. I agree with feneur that an invitation to AI devs needs more than a documentation. Given the recent media coverage in deep learning and other AI topics, it might be an idea to put AI/bots on the road map and reach out. I've seen trompetin17 reactivated the JS debugger, that's a very good start.

[Teiresias]

at l(e)ast we have a larger discussion group now... I will try and answer all points of the previous comments:

@feneur,mimo:
I have choosen JsDoc because it seemed the best "Doxygen for JavaScript" tool available - there are not too many of them anyway. Of course, this concept introduces the dependency on the source code, and I had to learn the JS language changes much faster than do traditional programming languages. So this approach has its drawbacks.

But, in my experience, a src->doc tool raises the chances of docs and src staying in sync, as both are "closer to each other". Separate documents tend to get neglected when the sources are updated, unless you have strict QA enforced. I even tend to write my designs into class/namespace overviews.

@niektb,mimo:
"struggled with basic tasks": I got a taste of it on my own today: In an attempt to write a quick-and-dirty driver for my defense system experiments, i attempted to use API3.Filters.byTerritory(), and failed to get it working. I found only one example of it in an elder aegis version, and that was not self-explaining. Finally, I considered it's faster to write my own version than debugging the existant one.

@niektb:
"unfortunately Aegis was difficult too": The elder testbot was simpler to understand, but has been dropped from the repository.

@mimo:
"improving the petra doc is in my plans, but I never find the time to do it": Based on my personal experience I can only recommend to write documentation immediately. Otherwise, you might never find the time once the task has grown real big.

@agentx:
"I've also thought of publishing here a minimal bot, (...) and you are knee deep in map analysis.": I can see that. Maybe this (c|sh)ould lead to a step-by-step tutorial which first uses a hard-coded bot on a hard-coded map, and then expands to more and more flexibility.

"I agree with feneur that an invitation to AI devs needs more than a documentation.": I agree with you. I just stumbled on the problem to figure how to use some of the API functions and thought I could help to improve a bit here.

[Stan`]

At least now we have Petra and Hannibal. Is your Ai documented AgentX ?

[agentx]

@Teiresias: Actually I meant a documentation is the base for any following step.

@Stan: I document everything stable in the github wiki. I think the code is mostly self explaining if the concepts used are familiar. And Hannibal is not ready, I hope to have a sandbox release in about 3 month.

[Teiresias]

Sorry - posted into wrong thread. Discussion is continued here:

https://wildfiregames.com/forum/index.php?/topic/20728-jsdoc-documentation

Edited May 15, 2016 by Teiresias
Posted into wrong thread