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 Thu, 21 Dec 2006 15:16:26 GMT
On the 0x246 day of Apache Harmony Svetlana Konovalova wrote:
> -----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?

my desire is not dead, time will come :)
I am dead from desire to see Doxygen on the website))

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

-- 
Egor Pasko


Mime
View raw message