Harmony
  1. Harmony
  2. HARMONY-3274

[drlvm][doc]scarce comments in vmcore external interface headers (JNI and JVMTI bundle)

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Won't Fix
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: DRLVM
    • Labels:
      None
    • Estimated Complexity:
      Advanced

      Description

      Many files lack ample and well-formatted comments; need to get easily readable, complete and useful reference for DRLVM Interface Reference and Java class library reference; the code commenting BKMs (http://wiki.apache.org/harmony/Code_Commenting) can be useful. Specific suggestions on improving Doxygen output are below.

      1. JNI_JVMTI_headers.patch
        84 kB
        Svetlana Konovalova

        Activity

        Hide
        Svetlana Konovalova added a comment -

        Here are suggestions on how to improve code comments of the VM Common interface (JNI and JVMTI bundle) so that Doxygen parses them correctly.

        GENERAL NOTE: I do respect the authors of all these headers and I do understand how proud they are to see their names in the comments! But, since it's the open source, I'd like to ask you to remove the authors' names from the files content. Thanks in advance and sorry about that!

        JNI

        include/jni_types.h
        -Add detailed description
        -Add brief description [@file]

        • Document functions
        • use appropriate formatting to make comments VISIBLE
        • use \ingroup, \defgroup

        include/jni.h
        -Add detailed description
        -Add brief description [@file]

        • Document functions

        JVMTI

        include/jvmti.h
        -Add detailed description
        -Add brief description [@file]

        • Document functions
          -Use appropriate formatting

        include/jvmti_types.h
        -Add detailed description
        -Add brief description [@file]

        • Document functions
        • use \ingroup, \defgroup (if applicable)
        Show
        Svetlana Konovalova added a comment - Here are suggestions on how to improve code comments of the VM Common interface (JNI and JVMTI bundle) so that Doxygen parses them correctly. GENERAL NOTE: I do respect the authors of all these headers and I do understand how proud they are to see their names in the comments! But, since it's the open source, I'd like to ask you to remove the authors' names from the files content. Thanks in advance and sorry about that! JNI include/jni_types.h -Add detailed description -Add brief description [@file] Document functions use appropriate formatting to make comments VISIBLE use \ingroup, \defgroup include/jni.h -Add detailed description -Add brief description [@file] Document functions JVMTI include/jvmti.h -Add detailed description -Add brief description [@file] Document functions -Use appropriate formatting include/jvmti_types.h -Add detailed description -Add brief description [@file] Document functions use \ingroup, \defgroup (if applicable)
        Hide
        Gregory Shimansky added a comment -

        I've added documentation to jni_types.h, jni.h, jvmti_types.h and jvmti.h files. Mostly comments are brief because JNI and JVMTI interfaces are specified on Sun page, so comments have links to Sun specification.

        Somehow doxygen has problems with function pointers typedefs like this:

        typedef void (JNICALL * jvmtiStartFunction)
        (jvmtiEnv * jvmti_env, JNIEnv * jni_env, void *arg);

        Such construction defines a type of pointer to a function with signature (jvmtiEnv * jvmti_env, JNIEnv * jni_env, void *arg). But doxygen parses this incorrectly, and typedefs section contains lots of garbage. This problem should be addressed separately.

        Fix applied at 523751.

        Show
        Gregory Shimansky added a comment - I've added documentation to jni_types.h, jni.h, jvmti_types.h and jvmti.h files. Mostly comments are brief because JNI and JVMTI interfaces are specified on Sun page, so comments have links to Sun specification. Somehow doxygen has problems with function pointers typedefs like this: typedef void (JNICALL * jvmtiStartFunction) (jvmtiEnv * jvmti_env, JNIEnv * jni_env, void *arg); Such construction defines a type of pointer to a function with signature (jvmtiEnv * jvmti_env, JNIEnv * jni_env, void *arg). But doxygen parses this incorrectly, and typedefs section contains lots of garbage. This problem should be addressed separately. Fix applied at 523751.
        Hide
        Svetlana Konovalova added a comment -

        IMHO, we should reopen the issue to add missing function descriptions, check grammar and correct formatting.

        Show
        Svetlana Konovalova added a comment - IMHO, we should reopen the issue to add missing function descriptions, check grammar and correct formatting.
        Hide
        Svetlana Konovalova added a comment -

        Gregory,
        Thanks a lot for the great job you've done! The headers look much better now!
        In my turn, I've corrected grammar, have fixed formatting and broken links.
        Feel free to find all the changes in the patch attached.
        Would be great if you could help me make these files 100% documented.

        AFAIS, we should resolve the following issues:

        jni.h
        Add missing Public Member Functions, Public Attributes descriptions.

        jni_types.h
        Add missing Public Attributes descriptions.

        jvmti.h
        Add missing Member Data Documentation and Member Function Documentation descriptions.

        jvmti_types.h
        Add missing Member Data Documentation descriptions.

        Don't hesitate to contact me in case you have any questions.
        Thanks in advance!

        Sveta

        Show
        Svetlana Konovalova added a comment - Gregory, Thanks a lot for the great job you've done! The headers look much better now! In my turn, I've corrected grammar, have fixed formatting and broken links. Feel free to find all the changes in the patch attached. Would be great if you could help me make these files 100% documented. AFAIS, we should resolve the following issues: jni.h Add missing Public Member Functions, Public Attributes descriptions. jni_types.h Add missing Public Attributes descriptions. jvmti.h Add missing Member Data Documentation and Member Function Documentation descriptions. jvmti_types.h Add missing Member Data Documentation descriptions. Don't hesitate to contact me in case you have any questions. Thanks in advance! Sveta
        Hide
        Gregory Shimansky added a comment -

        Sorry, not going to fix these minor problems.

        Show
        Gregory Shimansky added a comment - Sorry, not going to fix these minor problems.

          People

          • Assignee:
            Gregory Shimansky
            Reporter:
            Svetlana Konovalova
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development