harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Egor Pasko <egor.pa...@gmail.com>
Subject Re: [drlvm][doc]Improve documentation autogenerated from DRLVM sources [was:RE: [drlvm][doc] doxygen documentation]
Date Wed, 20 Dec 2006 16:11:58 GMT
On the 0x245 day of Apache Harmony Svetlana Konovalova wrote:
> >Thanks for the patches! I took a brief look - the patches seem fine.
> >However, I guess comments in these files can look still better if we
> >expand and/or change wording in some places. Volunteers welcome.
> 
> +1 The comments must be brushed up, no doubt. I could clean up language
> and continue with formatting... But my efforts are wasted without tech
> gurus' help. ) 

Sveta, thanks for formatting changes! 
Feel free to ask for tech gurus' help.

Here is what I can answer on your questions in [2]:

> ee_em_intf.h
> -Are there any [OUT] parameters?

no

> 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

they are preprocessor macros or whatever :)

> I'm not sure they should be documented the way they are now...

let them be a plain description, each of them can be defined in
several places of the file (and even not-defined), there is no need to
stick tocumentation to these specific places. Let the explanation just
be on top for now. Does that answer your question? :)

> Best regards,
> Sveta
> 
> -----Original Message-----
> From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com] 
> Sent: Wednesday, December 20, 2006 2:03 PM
> To: dev@harmony.apache.org
> Subject: RE: [drlvm][doc]Improve documentation autogenerated from DRLVM
> sources [was:RE: [drlvm][doc] doxygen documentation]
> 
> > To improve the situation, 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.
> 
> Thanks for the patches! I took a brief look - the patches seem fine.
> However, I guess comments in these files can look still better if we
> expand and/or change wording in some places. Volunteers welcome. 
> 
> Cheers, 
> Nadya
>  
> >-----Original Message-----
> >From: Konovalova, Svetlana [mailto:svetlana.konovalova@intel.com]
> >Sent: Wednesday, December 20, 2006 1:05 PM
> >To: dev@harmony.apache.org
> >Subject: [drlvm][doc]Improve documentation autogenerated from DRLVM
> sources
> >[was:RE: [drlvm][doc] doxygen documentation]
> >
> >
> >>Statistics on the quality/quantity of the Doxygen documentation is
> >>collected on the Wiki page,
> >>http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
> >
> >I've analysed the state of the DRLVM Intercomponent Interface header
> >files and created a pie chart, which you can find on the wiki page [1].
> >The analysis shows that we've got 1/3 of files with comments formatted
> >so that Doxygen just does not parse them. To improve the situation,
> 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. I've submitted a new
> >issue as well, so you can find the attached patch and my comments on
> how
> >to improve the same headers further right there [2].
> >Whould be great, if you could find a chance to look it through and let
> >me know whether I'm moving in the right direction.
> >Your feedback is very welcome!
> >Thanks in advance!
> >
> >Best regards,
> >Sveta
> >
> >[1]
> >http://wiki.apache.org/harmony/DRLVM_Intercomponent_Interface_Header-fi
> l
> >e_Status
> >[2] http://issues.apache.org/jira/browse/HARMONY-2802
> >
> >
> >-----Original Message-----
> >From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
> >Sent: Tuesday, December 19, 2006 5:26 PM
> >To: dev@harmony.apache.org
> >Subject: [drlvm][doc] doxygen documentation
> >
> >Hi all,
> >
> >I've committed new config files to drlvm/trunk/vm/doc so that you can
> >build Doxygen documentation for drlvm interfaces locally. These script
> >files are taken from HARMONY-2024. Suggestions/feedback welcome.
> >
> >Generated versions are stored at http://people.apache.org/~nadinem/ -
> >intf_doc, drlvm_intf_doc, and vmcore_doc. I'll regenerate once in while
> >to reflect recent functionality changes. Note that the files have the
> >nice starting page with the table (also taken from HARMONY-2024), but
> >you won't have it if you run Doxygen over your sources. To get the
> >starting page locally, apply the patch for vm.h to your source files.
> >
> >Statistics on the quality/quantity of the Doxygen documentation is
> >collected on the Wiki page,
> >http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
> >
> >Cheers Nadya
> 

-- 
Egor Pasko


Mime
View raw message