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: [drlvm][doc]Improve documentation autogenerated from DRLVM sources [was:RE: [drlvm][doc] doxygen documentation]
Date Thu, 21 Dec 2006 06:34:32 GMT
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:alexei.fedotov@gmail.com] 
Sent: Wednesday, December 20, 2006 9:06 PM
To: dev@harmony.apache.org
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 <svetlana.konovalova@intel.com> 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: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
>


-- 
With best regards,
Alexei,
ESSD, Intel

Mime
View raw message