JSON inputs and outputs are not documented anywhere

[antonsviridenko]

Description

Many FFI functions receive arguments in JSON format and/or return results in JSON. Like rnp_generate_key_json() rnp_signature_packet_to_json() and others having *_json in their name. The format of these input/output values is not documented anywhere.

Expected Behavior

Expected properties and data types should be described for each JSON parameter or return value.

[ronaldtse]

@antonsviridenko this is indeed very necessary. Could you help with it? Thanks!

[antonsviridenko]

I've just discovered that Doxygen-styled documentation for FFI API functions that we have in a header file rnp.h does not go anywhere, i.e. this source is not used to build any final document in HTML or any other human-readable format.

[ni4]

@antonsviridenko Yeah, currently docs are available only in the header file. Not sure about other IDEs, but in VS Code it is quite helpful:

[antonsviridenko]

rnp_key_to_json() and rnp_generate_key_json() have incompatible JSON formats describing keys... It would be nice to have some consistency in JSON formats, could be useful in cases where we get the existing key description, change some parameters and use resulting JSON as an input to generate the new key

[antonsviridenko]

@ni4 @ronaldtse Do we consider JSON format as a part of stable API? Or it could be changed between minor releases?

[ni4]

rnp_key_to_json() and rnp_generate_key_json() have incompatible JSON formats describing keys...

That's unfortunate, actually it would be much better to have matching formats. Is the difference major? If it's minor we may just accept both formats in rnp_generate_key_json().

Do we consider JSON format as a part of stable API? Or it could be changed between minor releases?

Yeah, it should be a part of stable API and it would not be desirable to change it.