harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nadya Morozova (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HARMONY-2802) Improve documentation autogenerated from DRLVM sources.
Date Wed, 24 Jan 2007 13:15:49 GMT

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

Nadya Morozova commented on HARMONY-2802:

I looked through your fresher patches for porting; a couple of suggestions:
- change any tabs to 4 spaces; many of your fixes break formatting
- don't overdo when adding whitespace: some one- or two- line comments become five or six
lines long which substantially extends file length without adding much content (e.g.: you
can place opening and closing * symbols on the same line for one line comments; you can remove
blank lines between parameters and return values, etc)
- don't overdo when adding extra spaces at the start and end of lines: end-of-line spaces
are useless and start-of-line spaces can break the formatting, especially for non-comment
code tags; 
- verify that your formatting changes are consistent; in several cases, names of functions
inside comments are not formatted, while in the majority of cases, they're in <code>

thanks, nadya

> Improve documentation autogenerated from DRLVM sources.
> -------------------------------------------------------
>                 Key: HARMONY-2802
>                 URL: https://issues.apache.org/jira/browse/HARMONY-2802
>             Project: Harmony
>          Issue Type: Improvement
>          Components: DRLVM
>            Reporter: Svetlana Konovalova
>         Assigned To: Nadya Morozova
>         Attachments: build_fix.patch, DRLVMheadersPatch2.patch, green.headers.patch,
HeadersPatch3.patch, port.headers.patch, VMCoreHeaders.patch
> 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
> ]
>  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
> -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]

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

View raw message