harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Konovalova, Svetlana" <svetlana.konoval...@intel.com>
Subject RE: Re: [drlvm][doc]Improve documentation autogenerated from DRLVM sources [was:RE: [drlvm][doc] doxygen documentation]
Date Thu, 21 Dec 2006 13:41:15 GMT

-----Original Message-----
From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
Sent: Wednesday, December 20, 2006 7:12 PM
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.
>

Thanks for giving a helping hand)
AFAYCS certain functions are not documented (see my comments [2]).
If you have time and desire, could you fill in these gaps? Or should I
contact the files' authors?
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 :)
Thanks for clarification :)

>> 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? :)

Yes, thanx :)

Cheers,
Sveta

> 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