Mailing-List: contact dev-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE: [drlvm][doc]Improve documentation autogenerated from DRLVM
 sources [was:RE: [drlvm][doc] doxygen documentation]
Date: Fri, 22 Dec 2006 19:37:07 +0300
Message-ID: 
 <32CD23D8C6B1454C9120C1525D521D67924989@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: [drlvm][doc]Improve documentation autogenerated from DRLVM
 sources [was:RE: [drlvm][doc] doxygen documentation]
Thread-Index: AcclAreI7kjihrw1SgSp+pXQwrdRowA43qWQ
From: "Konovalova, Svetlana" <svetlana.konovalova@intel.com>
To: <dev@harmony.apache.org>

I've created one more patch to fix the rest bunch of headers with
incorrect formatting. The patch includes the following files:=20
- include/jit_import.h=20
- vmcore/include/compile.h=20
- vmcore/include/environment.h=20
- vmcore/include/exceptions.h=20
- vmcore/include/jit_runtime_support_common.h=20
- vmcore/include/vm_strings.h=20
- include/jvmti_types.h=20
- include/open/jthread.h=20
- vmcore/include/jit_export.h=20
- vmcore/include/jit_export_jpda.h=20
- vmcore/include/jit_export_rt.h=20
- include/interpreter_exports.h

For the description of changes and information on how to improve the
headers, please refer to HARMONY-2802 [2].
Would be great, if you could have a look.

[2] http://issues.apache.org/jira/browse/HARMONY-2802

Best regards,
Sveta
-----Original Message-----
From: Alexei Fedotov [mailto:alexei.fedotov@gmail.com]=20
Sent: Thursday, December 21, 2006 4:19 PM
To: dev@harmony.apache.org
Subject: Re: [drlvm][doc]Improve documentation autogenerated from DRLVM
sources [was:RE: [drlvm][doc] doxygen documentation]

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 <svetlana.konovalova@intel.com> 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: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
>


--=20
With best regards,
Alexei,
ESSD, Intel