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, 14 Mar 2007 13:19:09 GMT

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

Nadya Morozova commented on HARMONY-2802:
-----------------------------------------

Hi Svetlana,
i'm now reviewing your second version of the patch for port headers' formatting. This is generally
very good. formatting will enable us to generate docs and fix writing style in this file.

Here are a couple of suggestions. Please address so that i can apply your patch:
- do you think we can set off big chunks of content into separate pages? for example, the
file lil.h has a longish description that can go on its own; we could separate the file definition
from the rest of the text and mark the latter with @page. what do you say?
- please don't change formatting in source code lines. if you limit yourself to comment lines
only, this would reduce patch size, review time, and will be safer for the environment :)

--Many of your fixes add an extra whitespace at the start of the code line. why do you need
that?
--Some files have more drastic changes, for example, function APR_DECLARE(uint8) port_atomic_cas8
in port_atomic.h (got the wrong alignment for parameters). such changes make reading code
more difficult. 
- can we try and minimize differences between commenting markup within a single file? so far,
we've tried to follow the rule of // as non-parsed comments and /** text */ or /// for parsed
comments. i don't think we need to mix the last two styles in a file. and why are more than
three slashes /// used for some comment lines? 
- can we stick to 80-symbol line length when possible? 
- when formatting file definitions, could you please ensure that the brief description and
details go separately? for some files , the resulting definition is all parsed as brief and
spreads for several lines of text. 
- what do occurrences like the following mean:   * @value[in] new value? did you mean @param[in]
value - new value? please don't forget to use the actual tag @param and add a dash (-) between
the parameter name and its definition (as recommended in our BKMs)

there's yet another issue that addresses port headers, HARMONY-3180. i'll look into the patch
in that issue to see if they in any way correlate.
keep up the good work.




> 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, PortHeaderFiles_update_February,9.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
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]
>  
>   

-- 
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