Sveta, thank you for explanations! My point was that removing and reformatting are different things. Developers usually don't object about reformatting, but they could have concerns about removing something.
That is why it worth to mention few removals in a cover letter for your patch. Thanks! On 12/21/06, Konovalova, Svetlana <[EMAIL PROTECTED]> wrote:
Alexei, I'd be glad to explain all the changes I made. They are practically the same for all headers. 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 These are major changes. Please let me know if you have questions. Would be glad to discuss any issues. Best regards, Sveta -----Original Message----- From: Alexei Fedotov [mailto:[EMAIL PROTECTED] Sent: Wednesday, December 20, 2006 9:06 PM To: [email protected] Subject: Re: [drlvm][doc]Improve documentation autogenerated from DRLVM sources [was:RE: [drlvm][doc] doxygen documentation] Hello, Sveta, You wrote, > 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 suggest explicitly mentioning the following format changes, so people won't be surprised. > I also removed removed the following @author tags from these files because... - @author Intel, Alexei Fedotov - @author Intel, Evgueni Brevnov, Ivan Volosyuk - @author Aleksey Ignatenko - @author Mikhail Y. Fursov - @author Intel, Alexei Fedotov - @author Intel, Alexei Fedotov Thanks! On 12/20/06, Konovalova, Svetlana <[EMAIL PROTECTED]> wrote: > > >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-fil > e_Status > [2] http://issues.apache.org/jira/browse/HARMONY-2802 > > > -----Original Message----- > From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] > Sent: Tuesday, December 19, 2006 5:26 PM > To: [email protected] > 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 > -- With best regards, Alexei, ESSD, Intel
-- With best regards, Alexei, ESSD, Intel
