Harmony
  1. Harmony
  2. HARMONY-3278

[drlvm][doc] scarce comments in Garbage collector and Execution engine external interface headers

    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

        Hide
        Svetlana Konovalova added a comment -

        Here are suggestions on how to improve code comments of the Thread manager component 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!

        Garbage collector

        include/open/gc.h

        • to start comments, use /** but not just/* (please fix mistakes)
        • Use \ingroup, \defgroup to get rid of such notes(even pictures), as
          /*
        • *****
        • *
        • * Routines to handle the GC area in the VTable.
        • *
        • *****
          */
        • Fix the wrong usage of /@{/ /@}/ commands. Comments are "hidden" because of mistaked usage of these commands.
        • Document functions

        Execution Engine

        vmcore/include/jit_export.h

        • Can we use \ingroup, \defgroup to get rid of //Optional functions that don't have to be provided.//; // //Required functions.//?
          -Add detailed description
        • Add brief description [@file]
        • Define parameters as [in]/[out]
        • Add missing descriptions

        vmcore/include/jit_export_jpda.h
        -Add detailed description

        • Add brief description [@file]
        • Define parameters as [in]/[out]
          -Use <br> tags split content in "Return"
        • @return
        • EXE_ERROR_NONE on success<br>
        • EXE_ERROR_INVALID_METHODID if the given method handle is invalid

        vmcore/include/jit_export_rt.h

        • can we use \ingroup, \defgroup to get rid of "begin Frame Contexts for JITs", "end Frame Contexts for JITs" etc?
        • Add detailed description
        • Add brief description [@file]
          -Add missing descriptions

        include/interpreter_exports.h

        • Can we use \ingroup, \defgroup to get rid of "Open interfaces part begins"?
        • Add detailed description
        • Add brief description [@file]
        • Define parameters as [in]/[out]
        • Add missing descriptions
        Show
        Svetlana Konovalova added a comment - Here are suggestions on how to improve code comments of the Thread manager component 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! Garbage collector include/open/gc.h to start comments, use /** but not just/* (please fix mistakes) Use \ingroup, \defgroup to get rid of such notes(even pictures), as /* ***** * * Routines to handle the GC area in the VTable. * ***** */ Fix the wrong usage of / @{ / / @} / commands. Comments are "hidden" because of mistaked usage of these commands. Document functions Execution Engine vmcore/include/jit_export.h Can we use \ingroup, \defgroup to get rid of //Optional functions that don't have to be provided.//; // //Required functions.//? -Add detailed description Add brief description [@file] Define parameters as [in] / [out] Add missing descriptions vmcore/include/jit_export_jpda.h -Add detailed description Add brief description [@file] Define parameters as [in] / [out] -Use <br> tags split content in "Return" @return EXE_ERROR_NONE on success<br> EXE_ERROR_INVALID_METHODID if the given method handle is invalid vmcore/include/jit_export_rt.h can we use \ingroup, \defgroup to get rid of "begin Frame Contexts for JITs", "end Frame Contexts for JITs" etc? Add detailed description Add brief description [@file] -Add missing descriptions include/interpreter_exports.h Can we use \ingroup, \defgroup to get rid of "Open interfaces part begins"? Add detailed description Add brief description [@file] Define parameters as [in] / [out] Add missing descriptions

          People

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

            Dates

            • Created:
              Updated:

              Development