Harmony
  1. Harmony
  2. HARMONY-3262

[drlvm][doc] scarce comments in vmcore external interface headers (VM Common 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

        Hide
        Svetlana Konovalova added a comment -

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

        vm.h
        -Add brief description [@file]
        -Add detailed description (if necessary)
        -Document certain classes, defines, functions, enums, typedefs (where the description is missing)
        -Use \ingroup, \defgroup to get rid of such notes as: begin class iterator related functions;
        end class-related functions; end class-related functions; end method signature-related functions
        -Define parameters as [in]/[out]
        -Use @return & @note (I've added some...)

        bytecodes.h
        -Add brief description [@file]
        -Add detailed description (if necessary)

        common.h
        -Add brief description [@file]
        -Add detailed description (if necessary)

        vm_util.h
        -Add brief description [@file]
        -Add detailed description (AFAIU, there is detailed description, but it's formatted in a wrong way. Being marked as brief, it defines not the file in general, but the VMEXPORT void vm_create_helper_for_function
        function. Should it really be the way it is...?)
        -Document functions,classes, variables, typedefs(where the description is missing)
        -Can use \ingroup, \defgroup
        -Define parameters as [in]/[out]

        • The following files are marked as comments
          // #include "String_Pool.h"
          // #include "Class.h"
          // #include "object_layout.h"
          IMHO, they should be formatted in a right way if they really #INCLUDE, or removed otherwise.

        types.h
        -Add brief description [@file]
        -Add detailed description (if necessary)

        • Document typedefs, define (where the description is missing)
        • Are you sure we need "(? 20030317" and "? 02/7/25:" in the comment?

        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 Common interface so that Doxygen parses them correctly. vm.h -Add brief description [@file] -Add detailed description (if necessary) -Document certain classes, defines, functions, enums, typedefs (where the description is missing) -Use \ingroup, \defgroup to get rid of such notes as: begin class iterator related functions; end class-related functions; end class-related functions; end method signature-related functions -Define parameters as [in] / [out] -Use @return & @note (I've added some...) bytecodes.h -Add brief description [@file] -Add detailed description (if necessary) common.h -Add brief description [@file] -Add detailed description (if necessary) vm_util.h -Add brief description [@file] -Add detailed description (AFAIU, there is detailed description, but it's formatted in a wrong way. Being marked as brief, it defines not the file in general, but the VMEXPORT void vm_create_helper_for_function function. Should it really be the way it is...?) -Document functions,classes, variables, typedefs(where the description is missing) -Can use \ingroup, \defgroup -Define parameters as [in] / [out] The following files are marked as comments // #include "String_Pool.h" // #include "Class.h" // #include "object_layout.h" IMHO, they should be formatted in a right way if they really #INCLUDE, or removed otherwise. types.h -Add brief description [@file] -Add detailed description (if necessary) Document typedefs, define (where the description is missing) Are you sure we need "(? 20030317" and "? 02/7/25:" in the comment? Would be great if you could find a chance to fix the aforementioned issues. Thanks, Sveta

          People

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

            Dates

            • Created:
              Updated:

              Development