Sign in to follow this  

Documenting registered API

This topic is 836 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

This topic is 836 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this