Feature-Request JNAerator 0.12 - support for JavaDoc style code comments, fix misuse of JD style

[zsawyer]

I like JavaDoc and am therefore using it in my C and C++ programs too. It works well, I can even generate (i.e. HTML) documentation using doxygen.

This is my C-Code:

    /**
     * sets and commits the identity
     *
     * Notice: The identity does not need to be updated every single frame. It
     * shouldn't change more than a few times per second if at all during a game.
     *
     *      see <code>setIdentity(...)</code> for details
     *
     * @param identity  unique id of the user in a given context
     *
     * @return  an error code, see <code>enum LINKAPI_ERROR_CODE</code>
     */
    LINKAPI_API
    LINKAPI_ERROR_CODE commitIdentity(const wchar_t identity[LINKAPI_MAX_IDENTITY_LENGTH]);

It is transferred into this (BridJ):

    /**
     * Original signature : <code>LINKAPI_ERROR_CODE setIdentity(const wchar_t[256])</code><br>
     * <i>native declaration : line 230</i>
     */
    native public static IntValuedEnum<LinkAPILibrary.LINKAPI_ERROR_CODE > setIdentity(Pointer<Character > identity);

I now have 2 problems:

1. As the interface is part of an API that I want to distribute, it needs the documentation. But it was not transferred.
2. Instead of the original documentation comments JNAerator generates a comment (which is also useful) about the original code. But it uses JavaDoc /** syntax.

To get my documentation to work and still keep the information of the origin (which the end user might not care about). I Manually edit and paste the JD-comment over from the C-code.

This is my result:

    /**
     * sets and commits the identity
     *
     * Notice: The identity does not need to be updated every single frame. It
     * shouldn't change more than a few times per second if at all during a game.
     *
     *      see <code>setIdentity(...)</code> for details
     *
     * @param identity  unique id of the user in a given context
     *
     * @return  an error code, see <code>enum LINKAPI_ERROR_CODE</code>
     */
    /*
     * Original signature : <code>LINKAPI_ERROR_CODE setIdentity(const wchar_t[256])</code><br>
     * <i>native declaration : line 230</i>
     */
    native public static IntValuedEnum<LinkAPILibrary.LINKAPI_ERROR_CODE > setIdentity(Pointer<Character > identity);

Note how it is not one comment but 2 and the BridJ comment was changed to use normal comment syntax (/*).

So I have 2 requests:

1. Please have JNAerator reuse the JavaDoc type comments (already seems to work for enums).
2. Please format the JNAerator comments to use /* instead of /** - This may be conditional to when JavaDoc comments are present and 1. was applied, but could in my opinion be done always

[ochafik]

Hi @zsawyer,

Thanks for your detailed feature request, much appreciated!
JNAerator was already meant to reuse existing comments, but it turns out the comment-detection logic was a bit too conservative (it failed to go up two lines above a declaration to fetch its comments as in your example).
I've updated it so your example works fine (latest 0.12-SNAPSHOT), although I didn't follow your suggestion of 2) (I assume you meant to separate JNAerator's "original signature" comment in /* */ format from the original javadoc in /** */ format, but I'd much rather merge the two in a single comment instead so they both appear in the resulting javadoc).
Cheers