[HARMONY-2802] [drlvm][doc] Improve documentation autogenerated from DRLVM sources.

• Type: Improvement
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Component/s: DRLVM
• Patch Info: Patch Available
• Estimated Complexity: Moderate
• Assignee: Nadya Morozova
• Reporter: Svetlana Konovalova
• Created: 19/Dec/06 17:51
• Updated: 23/Oct/07 10:10

Description

I've created the patch to fix formatting in the following files located in include/ folder: vm.h, vm_util.h, jit_import_rt.h, common.h, jit_runtime_support.h, hycomp.h, ee_em_intf.h. Please be aware i've only fixed format of comments. Please find my comments on how to improve the same headers further:

common.h
-Add detailed description
-Add brief description [@file]

ee_em_intf.h
-Are there any [OUT] parameters?

hycomp.h
-Add detailed description
-Add brief description [@file]
-Add Defines and Typedefs descriptions (where necessary)
-There is the list of functions( or whatever) defining HY_PLATFORM_DOUBLE_ORDER
I'm not sure they should be documented the way they are now...
-Use @note for note text, but not just NOTE

jit_import_rt.h
-Seems to be fine

jit_runtime_support.h
-Add detailed description
-Add brief description [@file]
-Document functions, enums, typedefs (where the description is missing)
-Use @note for note text, but not just NOTE
-Group related functionalities together
[Object creation routines; Exception throwing routines; Type access routines; Deprecated routines;etc
]
using \ingroup, \defgroup, \addtogroup [<http://www.stack.nl/~dimitri/doxygen/grouping.html>
]
-Use @return, @param where necessary

vm.h
-Add detailed description
-Add brief description [@file]
-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...)

vm_util.h
-Add detailed description
-Add brief description [@file]
-Document functions,classes, variables, typedefs(where the description is missing)
-Can use \ingroup, \defgroup
-Define parameters as [in]/[out]

Issue Links

• is part of: HARMONY-3284 [drlvm][doc] scarce comments in OS portability layer external interface headers