Harmony
  1. Harmony
  2. HARMONY-3273

[drlvm][doc] scarce comments in vmcore external interface headers (VM_GC and VM_Thread 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 (VM_GC and VM_Thread 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!

        VM_GC

        include/open/vm_gc.h
        -Add detailed description (if necessary)
        -Document functions (where the description is missing)

        • Can we use smth like \ingroup, \defgroup to get rid of
        • *****
        • *
        • * Routines to support finalization of objects.
        • *
        • *****
          */

        include/slot.h

        • Add missing descriptions
          -use appropriate formatting
          -Use @return, @param where necessary

        VM_Thread

        include/open/thread_externals.h
        -Add detailed description
        -Add brief description [@file]
        -Add missing functions descriptions

        Show
        Svetlana Konovalova added a comment - Here are suggestions on how to improve code comments of the VM Common interface (VM_GC and VM_Thread 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! VM_GC include/open/vm_gc.h -Add detailed description (if necessary) -Document functions (where the description is missing) Can we use smth like \ingroup, \defgroup to get rid of ***** * * Routines to support finalization of objects. * ***** */ include/slot.h Add missing descriptions -use appropriate formatting -Use @return, @param where necessary VM_Thread include/open/thread_externals.h -Add detailed description -Add brief description [@file] -Add missing functions descriptions

          People

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

            Dates

            • Created:
              Updated:

              Development