You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by "Svetlana Konovalova (JIRA)" <ji...@apache.org> on 2007/02/28 09:23:05 UTC
[jira] Commented: (HARMONY-3262) [drlvm]scarce comments in vmcore
external interface headers (VM Common bundle)
[ https://issues.apache.org/jira/browse/HARMONY-3262?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12476548 ]
Svetlana Konovalova commented on HARMONY-3262:
----------------------------------------------
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
> [drlvm]scarce comments in vmcore external interface headers (VM Common bundle)
> -------------------------------------------------------------------------------
>
> Key: HARMONY-3262
> URL: https://issues.apache.org/jira/browse/HARMONY-3262
> Project: Harmony
> Issue Type: Bug
> Components: DRLVM
> Reporter: Svetlana Konovalova
>
> 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.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.