Transport Tycoon Forums

I see the doxygen generated for libraries as documentation for those using the library. And in that case I'd exclude library.nut as it only contains methods accessible to OpenTTD, but not accessible for a GS script including the library. Eg. it would be misleading to show those methods to a library user.

Btw, AIs/GSs provide info.nut to register with OpenTTD. AI libraries and GS libraries do this registration in library.nut. Those filenames are enforced by OpenTTD.

For an AI/GS I don't see much point in a doxygen document. But if you would use one I assume it is the programmer of that AI/GS and then I don't think it matter much if info.nut is included or not. I would not include it as it is not part of the AI/GS. Those methods are not accessible from the AI/GS side. Only OpenTTD can call them. And their names are enforced by OpenTTD and documented in docs http://noai.openttd.org/api/ and http://nogo.openttd.org/api/ .

I agree that AI/GS libraries documentation will be mostly used as API reference and as such at least library.nut is not really needed in documentation.
Note that if it is included you can lessen the confusion by giving the class in library.nut a different name than your main class. See e.g. AILib.List for an example of that.

Personally I find the documentation also useful for AI's and GS's themselves, although not really needed to have that online. Especially if you have multiple files and only work on it once in a while it can be difficult to remember what all classes and members do. Doxygen documentation gives you an easy way to get an overview.
For this use case it probably is even useful to be able to see the private parts in contrary to libraries.

I checked the doxygen commands for marking something as private.
You can do that with @private for only the next function or variable; or @privatesection which I suppose keeps everything private until you start a @publicsection.

I had a short look at a few of the libraries and most of them didn't look too bad. I will have a closer look probably this weekend.

A small update to the doxygen filter. It now marks variables, enums and functions starting with an underscore inside classes as private.

There are two other methods of marking something as private for doxygen which are explained on the Adding Doxygen documentation to your AI library wiki page I created.

Next: find some time to look at the libraries to make the documentation Doxygen ready where necessary.

I've slightly updated the build script for the Squirrel2Doxygen filter. Any new commit to this project will now trigger also an update the documentation for a number of libraries