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] Updated: (HARMONY-2802) Improve documentation autogenerated from DRLVM sources.
Date Fri, 22 Dec 2006 16:27:22 GMT
     [ http://issues.apache.org/jira/browse/HARMONY-2802?page=all ]

Svetlana Konovalova updated HARMONY-2802:
-----------------------------------------

    Attachment: DRLVMheadersPatch2.patch

DRLVMheadersPatch2.patch fixes the rest bunch of headers with incorrect  formatting. the patch
includes the folloing files:
- include/jit_import.h                                  
- vmcore/include/compile.h                             
- vmcore/include/environment.h                         
- vmcore/include/exceptions.h    
- vmcore/include/jit_runtime_support_common.h           
- vmcore/include/vm_strings.h   
- include/jvmti_types.h                                 
- include/open/jthread.h
- vmcore/include/jit_export.h                           
- vmcore/include/jit_export_jpda.h                      
- vmcore/include/jit_export_rt.h  
- include/interpreter_exports.h                       
                                                        
I made the following changes:

1) to make the comments visible after parsing, I've repleces the
following occurences
  /* <text> */

  ////
  // <text>
  ////

 with

 /**
   * <text>
   */
 As said in the Doxygen manual.

 2) for arguments and parameters, following Doxygen formatting rules,

   replaced "Parameter" with @param

 3) for return values, following Doxygen formatting rules, replaced
   "Return(s)" with @return

 4) removed @author, because all donated text should belong to Harmony,
 so   authors are actually erased, though I'm not clear about the policy.
  Please right me if I'm wrong here.

 5) for note text, replaced NOTE with @note.

 6) used <code> markup for classes, variables, etc
 
 7)used @sa to replace "see also"

8) added @name to turn a comment block into a header definition of a member group (for jit_import.h)

Would be nice to improve:


compile.h
-  Add detailed description 
-  Add brief description [@file] 
-  Add Define, Variable and Typedefs descriptions (where necessary) 
-  Remove the steps of author's hesitation :) [e.g.// does this method need an override?]
environment.h
-  Add detailed description 
-  Add brief description [@file] 
-  Add Typedefs descriptions (where necessary) 

exceptions.h 
-  I'm not sure about this (isn't displayed):
/**
\ page page1 exceptions Exceptions subsystem
\section section1 exn_introduction Introduction
The functions to work with exceptions are described in exceptions.h.
\section section1 exn_issues Issues
\li Interaction with JIT and runtime helpers? -salikh
\li Interaction with JIT is implemented via rth_wrap_exn_throw stubs. -pavel.n.afremov
\li Existing interface is currently included.
*/
IMHO we should fix this (have not figured out how to do this yet, and suggestions?) and remove
names; 
-  Add detailed description 
-  Add missing descriptions
-  Can we use \ingroup, \defgroup to  get rid of, let's say, / FUNCTIONS below are from old
VM implementation / note?

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

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

jit_export_jpda.h
- Add detailed description 
- Add brief description [@file] 
- Define parameters as [in]/[out]

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


jit_import.h
- Added @name to turn a comment block into a header definition of a member group. 
- Add brief description [@file] 
- Add missing descriptions
- Add missing descriptions
- Remove the steps of author's hesitation :) [e.g. 
(or any of its subclasses?)]
- Avoid descriptions given in brackets. This info is perceived as redundant and excessive,
and is often omitted by the readers.
- Define parameters as [in]/[out]


jit_runtime_support_common.h 
- Add brief description [@file] 
- Add missing descriptions

jthread.h
-Add missing descriptions

vm_strings.h
- Add brief description [@file] 
- Add missing descriptions
- Encode characters <code>offset..offset+count-1</code> into UTF8 and place in
buf."
The sentence is broken, would be great if someone could fix this. The point is that Doxygen
breaks the first sentence in the definition after the first full stop it finds.


 your feedback end helping hand are v/welcome




> Improve documentation autogenerated from DRLVM sources.
> -------------------------------------------------------
>
>                 Key: HARMONY-2802
>                 URL: http://issues.apache.org/jira/browse/HARMONY-2802
>             Project: Harmony
>          Issue Type: Improvement
>          Components: DRLVM
>            Reporter: Svetlana Konovalova
>         Attachments: DRLVMheadersPatch2.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.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

Mime
View raw message