harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Svetlana Konovalova (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HARMONY-3278) [drlvm]scarce comments in Garbage collector and Execution engine external interface headers
Date Thu, 01 Mar 2007 15:06:52 GMT

    [ https://issues.apache.org/jira/browse/HARMONY-3278?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12476962
] 

Svetlana Konovalova commented on HARMONY-3278:
----------------------------------------------

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


> [drlvm]scarce comments in Garbage collector and Execution engine external interface headers
> -------------------------------------------------------------------------------------------
>
>                 Key: HARMONY-3278
>                 URL: https://issues.apache.org/jira/browse/HARMONY-3278
>             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.


Mime
View raw message