Well, the current AGS scripting help is sorted alphabetically (by class), and looks like it wouldn't be out of place in source comments, IMO. (But on that last point it's really the developers' opinions that count.) I assume it would go in either the .cpp or .h files
In my experience with C++, near the actual implementation works best, as that gets changed when you change semantics of the call. It also helps in keeping the .h file less cluttered so it is easy to read.
As you can see, there is no documentation in the source code currently, so there wouldn't be any conflict.
I browsed through the code for half an hour to see if I could understand what belonged together but didn't get very far.
As for lack of comments, yeah, I noted. It's the same with almost every open source project. It's unfortunate that people (no offense intended to anyone, it's just an observation) don't take 1/2 a minute to write a few lines about the call interface (in terms that are easy to understand if you don't know the function) when they have it fresh in memory, so everybody now and in the future can read it in 10 seconds and have all relevant details on the first try, instead of having to reverse-engineer the interface in 30+ 1/2 minutes with the additional risks of missing some crucial implicit note or assumption which will surface as a bug 6 months later, which takes an amount of time that is not really usefully countable in 1/2 minutes.
I started systematically documenting every function/method I wrote since about 8 years ago, and I found
it increased my productivity. It takes a lot less mental effort to read 4 lines explaining how to call some function I wrote 3 years ago than it takes to reverse engineer that function without messing up. It makes the difference between "just call that function and get on with the problem you're working on" versus "oh my god, what did I do here again? There was something special here, I need more coffee.". I can also handle larger code bases with less effort now.
Besides the .rst patch, I haven't done anything in the AGS project yet. (Trying to read the manual failed already :p ) I do like the application domain, but I already write compilers/execution engines as day job. AGS doesn't run natively at my linux system, which makes it very hard to do anything useful.
If I decide to do more code-oriented things, documentation will be high on my list in this project. My standard tactic in such a case is to start throwing documentation patches at the project (I don't want to reverse engineer anything more than once). However, if such patches are refused or existing devs see no reason to stop adding undocumented code or don't update existing documentation, I'll stop fairly quickly as well. No offense, but there is no point in me doing such work if new work gets created as we speak, so to say.
It's not correct that AGS currently has "one manual for all versions." Rather, it has a different version of the manual for each different version of AGS (distributed with the build), but only the latest version (at least in theory) is online.
Oh sorry, didn't know that. I normally never use builds, I tend to compile everything from source, as sooner or later I want to fix something annoying

by putting reStructuredText comments throughout the code, we're more tied to Sphinx; it would be a little bit harder to switch to a different HAT in the future.
Less than you're now tied to tex2rtf & friends. Unlike the current tex source, there is a free RST parser framework available in Python (docutils project iirc) that you can use if you want to. Writing a simple line-based text conversion script like I did, and pushing all the source code in a somewhat uniform format took a few days. As long as you stick to mostly plain text, it can be converted relatively easily.