Documenting registered API

Started by
3 comments, last by WitchLord 8 years, 8 months ago

Is there a way in AngelScript to obtain a list of entities that have been registered with the engine?

Basically, I have an API defined by things I register with my AngelScript engine. That API incremently grows with each version of my program. We document the API with a page on our project's Wiki. I should update the Wiki each time the API changes...

In practice, I have proven to be very bad at keeping that Wiki up to date.

However, if I could query the engine for everything registered, I could either write out some html documentation -- or possibly write out an 'equivalent' header file to the process through Doxygen or similar. I could then maintain a website of API docs mapped to the exact version with each release.

Perhaps there is a way to extend the annotation of things registered with AngelScript to provide some built-in documentation. This would be included with the documentation query above -- or possibly allow script users to query the engine for everything that has been registered.

Thanks for any suggestions,

Rob

Advertisement

The function WriteConfigToStream in the add_on/scripthelper/scripthelper.cpp file shows how to enumerate the registered interface.

As for storing comments with the registered interface, you can quite easily accomplish this by storing them as user data with each registered entity, or you could keep them in a separate map outside of the script engine.

As for myself I just keep this as code comments within the application code, and use Doxygen to generate the documentation from that. Of course, this doesn't guarantee that the code comments are kept up-to-date with the change in registered interface, but at least the registration and documentation is done at the same place which makes it a lot easier to remember to do the updates.

AngelCode.com - game development and more - Reference DB - game developer references
AngelScript - free scripting library - BMFont - free bitmap font generator - Tower - free puzzle game

We currently have a wrapper around the registration functions which takes a const char* for documentation. This is stored in a separate list, which is written out to a file in a simple, xml like format.

A separate program then generates html from that.

I've been thinking about using some sort of clang tool to extract documentation from annotations placed before calls to the registration functions, but i don't know if such annotations would be picked up by the compiler, and getting clang tools to work on Windows has been unsuccessful so far.

Thanks much for the suggestions.

Andreas - from what I can tell, the user data approach doesn't really extend to Enums. It may still be the way to go.

Solokiller - annotations and clang tools is a bit more ambitious than I had in mind. If you do come up with something, it would be great to see it made available.

You're right. Currently the library interface doesn't provide support for storing user data for registered enums. I'll see if I can think of a good and clean way of exposing this support to the application.

AngelCode.com - game development and more - Reference DB - game developer references
AngelScript - free scripting library - BMFont - free bitmap font generator - Tower - free puzzle game

This topic is closed to new replies.

Advertisement