Harmony
  1. Harmony
  2. HARMONY-3264

[drlvm][doc]scarce comments in vmcore external interface headers (VM_Interpreter bundle)

    Details

    • Type: Bug Bug
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • 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.

        Activity

        Svetlana Konovalova made changes -
        Field Original Value New Value
        Summary [drlvm]scarce comments in vmcore external interface headers (VM_Interpreter bundle) [drlvm][doc]scarce comments in vmcore external interface headers (VM_Interpreter bundle)
        Hide
        Svetlana Konovalova added a comment -

        Here are suggestions on how to improve code comments of the VM_Interpreter interface so that Doxygen parses them correctly.

        include/interpreter_imports.h
        -Add detailed description (if necessary)

        • Document functions

        vmcore/include/Class.h
        -Add brief description [@file]

        • Document functions (where description is missing)
        • Use \ingroup, \defgroup to get rid of such notes as:
          // forward declarations
          // external declarations
        • Сheck formatting

        vmcore/include/compile.h

        • Add brief description [@file]
          -Add detailed description (if necessary)
        • Document functions (where description is missing)

        vmcore/include/environment.h

        • Add brief description [@file]
          -Add detailed description (if necessary)
        • Document functions

        vmcore/include/exceptions.h
        -Add detailed description (if necessary)

        • Document functions

        vmcore/include/exceptions_int.h

        • Add brief description [@file]
          -Add detailed description (if necessary)
        • Document functions

        vmcore/include/jit_export.h

        • Add brief description [@file]
          -Add detailed description (if necessary)
        • Document functions (where description is missing)
        • Use \ingroup, \defgroup to get rid of such notes as:
          ////////////////////////////////////////////////////
          // Optional functions that don't have to be provided.
          ////////////////////////////////////////////////////
          or
          ////////
          //Required functions.
          ////////

        vmcore/include/jit_runtime_support_common.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions (where description is missing)

        vmcore/include/mon_enter_exit.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions (where description is missing)

        vmcore/src/util/linux/include/platform_lowlevel.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions

        vmcore/src/util/win/include/platform_lowlevel.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions

        vmcore/include/thread_generic.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document the function

        vmcore/include/thread_manager.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions (where description is missing)

        vmcore/include/vm_arrays.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions (where description is missing)

        vmcore/include/vm_core_types.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions

        vmcore/include/vm_strings.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions
        • Use \ingroup, \defgroup to get rid of such notes as:
          //*** Handle versions
          //***** New Interface

        vmcore/include/vm_threads.h

        • Add brief description [@file]
        • Add detailed description (if necessary)
        • Document functions (where description is missing)
        • Use appropriate formatting

        Would be great if you could find a chance to fix the aforementioned issues.

        Thanks,
        Sveta

        Show
        Svetlana Konovalova added a comment - Here are suggestions on how to improve code comments of the VM_Interpreter interface so that Doxygen parses them correctly. include/interpreter_imports.h -Add detailed description (if necessary) Document functions vmcore/include/Class.h -Add brief description [@file] Document functions (where description is missing) Use \ingroup, \defgroup to get rid of such notes as: // forward declarations // external declarations Сheck formatting vmcore/include/compile.h Add brief description [@file] -Add detailed description (if necessary) Document functions (where description is missing) vmcore/include/environment.h Add brief description [@file] -Add detailed description (if necessary) Document functions vmcore/include/exceptions.h -Add detailed description (if necessary) Document functions vmcore/include/exceptions_int.h Add brief description [@file] -Add detailed description (if necessary) Document functions vmcore/include/jit_export.h Add brief description [@file] -Add detailed description (if necessary) Document functions (where description is missing) Use \ingroup, \defgroup to get rid of such notes as: //////////////////////////////////////////////////// // Optional functions that don't have to be provided. //////////////////////////////////////////////////// or //////// //Required functions. //////// vmcore/include/jit_runtime_support_common.h Add brief description [@file] Add detailed description (if necessary) Document functions (where description is missing) vmcore/include/mon_enter_exit.h Add brief description [@file] Add detailed description (if necessary) Document functions (where description is missing) vmcore/src/util/linux/include/platform_lowlevel.h Add brief description [@file] Add detailed description (if necessary) Document functions vmcore/src/util/win/include/platform_lowlevel.h Add brief description [@file] Add detailed description (if necessary) Document functions vmcore/include/thread_generic.h Add brief description [@file] Add detailed description (if necessary) Document the function vmcore/include/thread_manager.h Add brief description [@file] Add detailed description (if necessary) Document functions (where description is missing) vmcore/include/vm_arrays.h Add brief description [@file] Add detailed description (if necessary) Document functions (where description is missing) vmcore/include/vm_core_types.h Add brief description [@file] Add detailed description (if necessary) Document functions vmcore/include/vm_strings.h Add brief description [@file] Add detailed description (if necessary) Document functions Use \ingroup, \defgroup to get rid of such notes as: //*** Handle versions //***** New Interface vmcore/include/vm_threads.h Add brief description [@file] Add detailed description (if necessary) Document functions (where description is missing) Use appropriate formatting Would be great if you could find a chance to fix the aforementioned issues. Thanks, Sveta
        Svetlana Konovalova created issue -

          People

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

            Dates

            • Created:
              Updated:

              Development