Documentation: function signatures for debug callbacks are undocumented

[GravisZro]

The duk_debugger_attach function takes pointers to seven callback functions but none of the function signatures are documented. This is true for both the API documentation and the internal debugger documentation file (/doc/debugger.rst).

Furthermore, the purpose of void *udata isn't documented.

[lemmel]

Hi

First there is a full example that is provided: examples/debug-trans-dvalue

As to the signature, the write callback: duk_size_t duk_trans_dvalue_write_cb(void *udata, char *buffer, duk_size_t length)

I suppose that buffer and length do not suprise you (the length of the buffer that contains the data to write), so the udata: it is something usual when working with C APIs as it allows the API user to have some "personnal" informations about the callback.

To be more precise, without the udata (stand for user data), Duktape would probably provide a context (i.e. a duk_context) and that would be all: no way for you to have a pointer to your singleton, your Duktape's manager or whatever. By allowing the user to provide its own data (through a **void***), Duktape allows you to do what you want.

To be more specific with an example and without a udata: the write callback allows you to receive data from Duktape, but a full message may be splitted in several parts forcing you to use a global variable/function to aggregate all the parts before to be able to do any work. With a udata, you are able to have several instances of the engine (one by duk_create_heap_default call), and so on.

I'm currently coding with Duktape and I started with the official example that I modified. Here and there I needed to read some part of the documentation but all in all, the library is not surprising when you are accustomed with C APIs.

Was this comment of any help to you ?