You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Konovalova, Svetlana" <sv...@intel.com> on 2007/03/02 13:09:32 UTC
[drlvm][doc] fix comments in vmcore external interface headers
Dear all,
Many source header files for generating readable Doxygen
reference materials [10] lack ample and well-formatted comments. Our aim
is to get easily readable, complete and useful reference for DRLVM
Interface Reference and Java class library reference.
In this connection, I've opened the following JIRAs including
suggestions on improving Doxygen output. Would be great if you could
find time to look through them and provide patches. The code commenting
BKMs [11] can be useful.
[1] http://issues.apache.org/jira/browse/HARMONY-3262
Covers VM_Common interface header files
[2] http://issues.apache.org/jira/browse/HARMONY-3263
Covers VM_JIT and VM_EM interface header files
[3] http://issues.apache.org/jira/browse/HARMONY-3264
Covers VM_Interpreter interface header files
[4] http://issues.apache.org/jira/browse/HARMONY-3273
Covers VM_GC interface and VM_Thread interface header files
[5] http://issues.apache.org/jira/browse/HARMONY-3274
Covers JNI and JVMTI interface header files
[6] http://issues.apache.org/jira/browse/HARMONY-3275
Covers Execution manager external interface headers
[7] http://issues.apache.org/jira/browse/HARMONY-3277
Covers Thread manager external interface headers
[8] http://issues.apache.org/jira/browse/HARMONY-3278
Covers Garbage collector and Execution engine external interface
headers
[9] http://issues.apache.org/jira/browse/HARMONY-3284
Covers OS portability layer external interface
Best regards,
Sveta
[10]
http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
ml
[11] http://wiki.apache.org/harmony/Code_Commenting
-----Original Message-----
From: Konovalova, Svetlana
Sent: Wednesday, February 28, 2007 1:49 PM
To: 'dev@harmony.apache.org'
Subject: [drlvm]fix comments in vmcore external interface headers
<was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>You can get involved in one of the following areas or open new JIRAs
>with your own suggestions/fixes:
Trying to improve scarce comments in VM Core external interface headers,
I've opened the following JIRAs with improvement suggestions:
[1] http://issues.apache.org/jira/browse/HARMONY-3262
Covers VM_Common interface header files
[2] http://issues.apache.org/jira/browse/HARMONY-3263
Covers VM_JIT and VM_EM interface header files
[3] http://issues.apache.org/jira/browse/HARMONY-3264
Covers VM_Interpreter interface header files
Would be great if you could find time to look through the proposed
changes and provide patches. :)
Best regards,
Sveta
-----Original Message-----
From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
Sent: Tuesday, February 20, 2007 7:33 PM
To: dev@harmony.apache.org
Subject: [doxygen][doc] commenting bkms draft published on wiki
Hi everyone,
I have posted several tips/suggestions [1] about writing nice code
comments in source header files for generating readable Doxygen
reference materials [2]. These guidelines are to define some ground
formatting and stylistic rules that would be good to follow when adding
comments to code.
Your feedback is most welcome because together we can find the best
solutions.
The current reference documentation is often incomplete, out-of-date
and/or not formatted correctly, which greatly decreases its usefulness.
Volunteers are very welcome to supply patches with more commented code.
The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
so classlib input is also welcomed.
You can get involved in one of the following areas or open new JIRAs
with your own suggestions/fixes:
[3] improving formatting of code comments so that Doxygen parses them
correctly
[4] enabling creation of structurally meaningful doc bundles and adding
intros (mainpage content) to each bundle
[5] beautifying Doxygen output
[6] monitoring quality and quantity of available Doxygen documentation
Thanks,
Nadya Morozova
[1] http://wiki.apache.org/harmony/Code_Commenting
[2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
[3] https://issues.apache.org/jira/browse/HARMONY-2802
[4] https://issues.apache.org/jira/browse/HARMONY-2814
[5] http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
[6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
Re: [drlvm][doc] fix comments in vmcore external interface headers
Posted by Nathan Beyer <nd...@apache.org>.
We've been removing author names all over, so I think Sveta is just
following that practice.
I understand the desire for giving credit, but maintaining author
attribution gets a little hairy. How many lines of a patch gives you
an author attribution? Et cetera.
It's much easier to not use author attributes in individual files and
place a bulk contributor list with releases. Admittedly, this is
probably not something we have setup yet.
-Nathan
On 3/2/07, Peter Novodvorsky <pe...@gmail.com> wrote:
> Sveta,
>
> I wanted to ask if it's really needed to remove authors names in
> source files. The reason "since it's the open source" doesn't sound
> well: just because it's opensource we _need_ to write authors names in
> source files. Linux does it, Mozilla does it, why we don't.
>
> Even if we can't write author names sometimes, we can just add patch
> authors as contributors to files. Mozilla has special field for
> contributors in source headers. This won't make files much bigger
> (really, do you mind adding two lines of comma-separated names in the
> source header? license takes *much* more).
>
> Give credit where credit is due.
>
> thanks.
> Peter.
>
>
> On 3/2/07, Alexey Varlamov <al...@gmail.com> wrote:
> > Sveta,
> > Have you seen HARMONY-3180 ([drlvm][doc] Improved portlib docs)?
> > It should address some of HARMONY-3284 items.
> >
> > --
> > Alexey
> >
> > 2007/3/2, Konovalova, Svetlana <sv...@intel.com>:
> > > Dear all,
> > >
> > > Many source header files for generating readable Doxygen
> > > reference materials [10] lack ample and well-formatted comments. Our aim
> > > is to get easily readable, complete and useful reference for DRLVM
> > > Interface Reference and Java class library reference.
> > > In this connection, I've opened the following JIRAs including
> > > suggestions on improving Doxygen output. Would be great if you could
> > > find time to look through them and provide patches. The code commenting
> > > BKMs [11] can be useful.
> > >
> > > [1] http://issues.apache.org/jira/browse/HARMONY-3262
> > > Covers VM_Common interface header files
> > >
> > > [2] http://issues.apache.org/jira/browse/HARMONY-3263
> > > Covers VM_JIT and VM_EM interface header files
> > >
> > > [3] http://issues.apache.org/jira/browse/HARMONY-3264
> > > Covers VM_Interpreter interface header files
> > >
> > > [4] http://issues.apache.org/jira/browse/HARMONY-3273
> > > Covers VM_GC interface and VM_Thread interface header files
> > >
> > > [5] http://issues.apache.org/jira/browse/HARMONY-3274
> > > Covers JNI and JVMTI interface header files
> > >
> > > [6] http://issues.apache.org/jira/browse/HARMONY-3275
> > > Covers Execution manager external interface headers
> > >
> > > [7] http://issues.apache.org/jira/browse/HARMONY-3277
> > > Covers Thread manager external interface headers
> > >
> > > [8] http://issues.apache.org/jira/browse/HARMONY-3278
> > > Covers Garbage collector and Execution engine external interface
> > > headers
> > >
> > > [9] http://issues.apache.org/jira/browse/HARMONY-3284
> > > Covers OS portability layer external interface
> > >
> > >
> > > Best regards,
> > > Sveta
> > >
> > > [10]
> > > http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
> > > ml
> > > [11] http://wiki.apache.org/harmony/Code_Commenting
> > >
> > >
> > >
> > > -----Original Message-----
> > > From: Konovalova, Svetlana
> > > Sent: Wednesday, February 28, 2007 1:49 PM
> > > To: 'dev@harmony.apache.org'
> > > Subject: [drlvm]fix comments in vmcore external interface headers
> > > <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
> > >
> > >
> > > >You can get involved in one of the following areas or open new JIRAs
> > > >with your own suggestions/fixes:
> > >
> > > Trying to improve scarce comments in VM Core external interface headers,
> > > I've opened the following JIRAs with improvement suggestions:
> > >
> > > [1] http://issues.apache.org/jira/browse/HARMONY-3262
> > > Covers VM_Common interface header files
> > > [2] http://issues.apache.org/jira/browse/HARMONY-3263
> > > Covers VM_JIT and VM_EM interface header files
> > > [3] http://issues.apache.org/jira/browse/HARMONY-3264
> > > Covers VM_Interpreter interface header files
> > >
> > > Would be great if you could find time to look through the proposed
> > > changes and provide patches. :)
> > >
> > > Best regards,
> > > Sveta
> > > -----Original Message-----
> > > From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
> > > Sent: Tuesday, February 20, 2007 7:33 PM
> > > To: dev@harmony.apache.org
> > > Subject: [doxygen][doc] commenting bkms draft published on wiki
> > >
> > > Hi everyone,
> > > I have posted several tips/suggestions [1] about writing nice code
> > > comments in source header files for generating readable Doxygen
> > > reference materials [2]. These guidelines are to define some ground
> > > formatting and stylistic rules that would be good to follow when adding
> > > comments to code.
> > > Your feedback is most welcome because together we can find the best
> > > solutions.
> > >
> > > The current reference documentation is often incomplete, out-of-date
> > > and/or not formatted correctly, which greatly decreases its usefulness.
> > > Volunteers are very welcome to supply patches with more commented code.
> > > The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
> > > so classlib input is also welcomed.
> > >
> > > You can get involved in one of the following areas or open new JIRAs
> > > with your own suggestions/fixes:
> > >
> > > [3] improving formatting of code comments so that Doxygen parses them
> > > correctly
> > > [4] enabling creation of structurally meaningful doc bundles and adding
> > > intros (mainpage content) to each bundle
> > > [5] beautifying Doxygen output
> > > [6] monitoring quality and quantity of available Doxygen documentation
> > >
> > > Thanks,
> > > Nadya Morozova
> > >
> > > [1] http://wiki.apache.org/harmony/Code_Commenting
> > > [2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
> > > [3] https://issues.apache.org/jira/browse/HARMONY-2802
> > > [4] https://issues.apache.org/jira/browse/HARMONY-2814
> > > [5] http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
> > >
> > > [6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
> > >
> >
>
Re: [drlvm][doc] fix comments in vmcore external interface headers
Posted by Peter Novodvorsky <pe...@gmail.com>.
Sveta,
I wanted to ask if it's really needed to remove authors names in
source files. The reason "since it's the open source" doesn't sound
well: just because it's opensource we _need_ to write authors names in
source files. Linux does it, Mozilla does it, why we don't.
Even if we can't write author names sometimes, we can just add patch
authors as contributors to files. Mozilla has special field for
contributors in source headers. This won't make files much bigger
(really, do you mind adding two lines of comma-separated names in the
source header? license takes *much* more).
Give credit where credit is due.
thanks.
Peter.
On 3/2/07, Alexey Varlamov <al...@gmail.com> wrote:
> Sveta,
> Have you seen HARMONY-3180 ([drlvm][doc] Improved portlib docs)?
> It should address some of HARMONY-3284 items.
>
> --
> Alexey
>
> 2007/3/2, Konovalova, Svetlana <sv...@intel.com>:
> > Dear all,
> >
> > Many source header files for generating readable Doxygen
> > reference materials [10] lack ample and well-formatted comments. Our aim
> > is to get easily readable, complete and useful reference for DRLVM
> > Interface Reference and Java class library reference.
> > In this connection, I've opened the following JIRAs including
> > suggestions on improving Doxygen output. Would be great if you could
> > find time to look through them and provide patches. The code commenting
> > BKMs [11] can be useful.
> >
> > [1] http://issues.apache.org/jira/browse/HARMONY-3262
> > Covers VM_Common interface header files
> >
> > [2] http://issues.apache.org/jira/browse/HARMONY-3263
> > Covers VM_JIT and VM_EM interface header files
> >
> > [3] http://issues.apache.org/jira/browse/HARMONY-3264
> > Covers VM_Interpreter interface header files
> >
> > [4] http://issues.apache.org/jira/browse/HARMONY-3273
> > Covers VM_GC interface and VM_Thread interface header files
> >
> > [5] http://issues.apache.org/jira/browse/HARMONY-3274
> > Covers JNI and JVMTI interface header files
> >
> > [6] http://issues.apache.org/jira/browse/HARMONY-3275
> > Covers Execution manager external interface headers
> >
> > [7] http://issues.apache.org/jira/browse/HARMONY-3277
> > Covers Thread manager external interface headers
> >
> > [8] http://issues.apache.org/jira/browse/HARMONY-3278
> > Covers Garbage collector and Execution engine external interface
> > headers
> >
> > [9] http://issues.apache.org/jira/browse/HARMONY-3284
> > Covers OS portability layer external interface
> >
> >
> > Best regards,
> > Sveta
> >
> > [10]
> > http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
> > ml
> > [11] http://wiki.apache.org/harmony/Code_Commenting
> >
> >
> >
> > -----Original Message-----
> > From: Konovalova, Svetlana
> > Sent: Wednesday, February 28, 2007 1:49 PM
> > To: 'dev@harmony.apache.org'
> > Subject: [drlvm]fix comments in vmcore external interface headers
> > <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
> >
> >
> > >You can get involved in one of the following areas or open new JIRAs
> > >with your own suggestions/fixes:
> >
> > Trying to improve scarce comments in VM Core external interface headers,
> > I've opened the following JIRAs with improvement suggestions:
> >
> > [1] http://issues.apache.org/jira/browse/HARMONY-3262
> > Covers VM_Common interface header files
> > [2] http://issues.apache.org/jira/browse/HARMONY-3263
> > Covers VM_JIT and VM_EM interface header files
> > [3] http://issues.apache.org/jira/browse/HARMONY-3264
> > Covers VM_Interpreter interface header files
> >
> > Would be great if you could find time to look through the proposed
> > changes and provide patches. :)
> >
> > Best regards,
> > Sveta
> > -----Original Message-----
> > From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
> > Sent: Tuesday, February 20, 2007 7:33 PM
> > To: dev@harmony.apache.org
> > Subject: [doxygen][doc] commenting bkms draft published on wiki
> >
> > Hi everyone,
> > I have posted several tips/suggestions [1] about writing nice code
> > comments in source header files for generating readable Doxygen
> > reference materials [2]. These guidelines are to define some ground
> > formatting and stylistic rules that would be good to follow when adding
> > comments to code.
> > Your feedback is most welcome because together we can find the best
> > solutions.
> >
> > The current reference documentation is often incomplete, out-of-date
> > and/or not formatted correctly, which greatly decreases its usefulness.
> > Volunteers are very welcome to supply patches with more commented code.
> > The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
> > so classlib input is also welcomed.
> >
> > You can get involved in one of the following areas or open new JIRAs
> > with your own suggestions/fixes:
> >
> > [3] improving formatting of code comments so that Doxygen parses them
> > correctly
> > [4] enabling creation of structurally meaningful doc bundles and adding
> > intros (mainpage content) to each bundle
> > [5] beautifying Doxygen output
> > [6] monitoring quality and quantity of available Doxygen documentation
> >
> > Thanks,
> > Nadya Morozova
> >
> > [1] http://wiki.apache.org/harmony/Code_Commenting
> > [2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
> > [3] https://issues.apache.org/jira/browse/HARMONY-2802
> > [4] https://issues.apache.org/jira/browse/HARMONY-2814
> > [5] http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
> >
> > [6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
> >
>
RE: [drlvm][doc] fix comments in vmcore external interface headers
Posted by "Morozova, Nadezhda" <na...@intel.com>.
Hi,
I've linked HARMONY-3180 and HARMONY-2814; will think of how to best
address HARMONY-3284 <> HARMONY-3180 relation (will need to look at the
HARMONY-3180 patch).
Cheers,
Nadya
>-----Original Message-----
>From: Konovalova, Svetlana [mailto:svetlana.konovalova@intel.com]
>Sent: Friday, March 02, 2007 3:50 PM
>To: dev@harmony.apache.org
>Subject: RE: [drlvm][doc] fix comments in vmcore external interface
headers
><was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>
>Alexey,
>HARMONY-3284 really incorporates HARMONY-3180. I haven't seen this
>before. Thanks.
>BTW, I've also noticed that the patch from HARMONY-3180 has much in
>common with HARMONY-2814 patches editing doc.properties, the mainpage
>and build.xml. Do you know that?
>
>Best regards,
>Sveta
>
>-----Original Message-----
>From: Alexey Varlamov [mailto:alexey.v.varlamov@gmail.com]
>Sent: Friday, March 02, 2007 3:23 PM
>To: dev@harmony.apache.org
>Subject: Re: [drlvm][doc] fix comments in vmcore external interface
>headers <was:RE: [doxygen][doc] commenting bkms draft published on
wiki>
>
>Sveta,
>Have you seen HARMONY-3180 ([drlvm][doc] Improved portlib docs)?
>It should address some of HARMONY-3284 items.
>
>--
>Alexey
>
>2007/3/2, Konovalova, Svetlana <sv...@intel.com>:
>> Dear all,
>>
>> Many source header files for generating readable Doxygen
>> reference materials [10] lack ample and well-formatted comments. Our
>aim
>> is to get easily readable, complete and useful reference for DRLVM
>> Interface Reference and Java class library reference.
>> In this connection, I've opened the following JIRAs including
>> suggestions on improving Doxygen output. Would be great if you could
>> find time to look through them and provide patches. The code
>commenting
>> BKMs [11] can be useful.
>>
>> [1] http://issues.apache.org/jira/browse/HARMONY-3262
>> Covers VM_Common interface header files
>>
>> [2] http://issues.apache.org/jira/browse/HARMONY-3263
>> Covers VM_JIT and VM_EM interface header files
>>
>> [3] http://issues.apache.org/jira/browse/HARMONY-3264
>> Covers VM_Interpreter interface header files
>>
>> [4] http://issues.apache.org/jira/browse/HARMONY-3273
>> Covers VM_GC interface and VM_Thread interface header files
>>
>> [5] http://issues.apache.org/jira/browse/HARMONY-3274
>> Covers JNI and JVMTI interface header files
>>
>> [6] http://issues.apache.org/jira/browse/HARMONY-3275
>> Covers Execution manager external interface headers
>>
>> [7] http://issues.apache.org/jira/browse/HARMONY-3277
>> Covers Thread manager external interface headers
>>
>> [8] http://issues.apache.org/jira/browse/HARMONY-3278
>> Covers Garbage collector and Execution engine external interface
>> headers
>>
>> [9] http://issues.apache.org/jira/browse/HARMONY-3284
>> Covers OS portability layer external interface
>>
>>
>> Best regards,
>> Sveta
>>
>> [10]
>>
>http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.h
t
>> ml
>> [11] http://wiki.apache.org/harmony/Code_Commenting
>>
>>
>>
>> -----Original Message-----
>> From: Konovalova, Svetlana
>> Sent: Wednesday, February 28, 2007 1:49 PM
>> To: 'dev@harmony.apache.org'
>> Subject: [drlvm]fix comments in vmcore external interface headers
>> <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>>
>>
>> >You can get involved in one of the following areas or open new JIRAs
>> >with your own suggestions/fixes:
>>
>> Trying to improve scarce comments in VM Core external interface
>headers,
>> I've opened the following JIRAs with improvement suggestions:
>>
>> [1] http://issues.apache.org/jira/browse/HARMONY-3262
>> Covers VM_Common interface header files
>> [2] http://issues.apache.org/jira/browse/HARMONY-3263
>> Covers VM_JIT and VM_EM interface header files
>> [3] http://issues.apache.org/jira/browse/HARMONY-3264
>> Covers VM_Interpreter interface header files
>>
>> Would be great if you could find time to look through the proposed
>> changes and provide patches. :)
>>
>> Best regards,
>> Sveta
>> -----Original Message-----
>> From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>> Sent: Tuesday, February 20, 2007 7:33 PM
>> To: dev@harmony.apache.org
>> Subject: [doxygen][doc] commenting bkms draft published on wiki
>>
>> Hi everyone,
>> I have posted several tips/suggestions [1] about writing nice code
>> comments in source header files for generating readable Doxygen
>> reference materials [2]. These guidelines are to define some ground
>> formatting and stylistic rules that would be good to follow when
>adding
>> comments to code.
>> Your feedback is most welcome because together we can find the best
>> solutions.
>>
>> The current reference documentation is often incomplete, out-of-date
>> and/or not formatted correctly, which greatly decreases its
>usefulness.
>> Volunteers are very welcome to supply patches with more commented
>code.
>> The BKMs, samples and quoted bugs are mostly based on DRLVM
materials,
>> so classlib input is also welcomed.
>>
>> You can get involved in one of the following areas or open new JIRAs
>> with your own suggestions/fixes:
>>
>> [3] improving formatting of code comments so that Doxygen parses them
>> correctly
>> [4] enabling creation of structurally meaningful doc bundles and
>adding
>> intros (mainpage content) to each bundle
>> [5] beautifying Doxygen output
>> [6] monitoring quality and quantity of available Doxygen
documentation
>>
>> Thanks,
>> Nadya Morozova
>>
>> [1] http://wiki.apache.org/harmony/Code_Commenting
>> [2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
>> [3] https://issues.apache.org/jira/browse/HARMONY-2802
>> [4] https://issues.apache.org/jira/browse/HARMONY-2814
>> [5]
>http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
>>
>> [6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
>>
RE: [drlvm][doc] fix comments in vmcore external interface headers
Posted by "Konovalova, Svetlana" <sv...@intel.com>.
Alexey,
HARMONY-3284 really incorporates HARMONY-3180. I haven't seen this
before. Thanks.
BTW, I've also noticed that the patch from HARMONY-3180 has much in
common with HARMONY-2814 patches editing doc.properties, the mainpage
and build.xml. Do you know that?
Best regards,
Sveta
-----Original Message-----
From: Alexey Varlamov [mailto:alexey.v.varlamov@gmail.com]
Sent: Friday, March 02, 2007 3:23 PM
To: dev@harmony.apache.org
Subject: Re: [drlvm][doc] fix comments in vmcore external interface
headers <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
Sveta,
Have you seen HARMONY-3180 ([drlvm][doc] Improved portlib docs)?
It should address some of HARMONY-3284 items.
--
Alexey
2007/3/2, Konovalova, Svetlana <sv...@intel.com>:
> Dear all,
>
> Many source header files for generating readable Doxygen
> reference materials [10] lack ample and well-formatted comments. Our
aim
> is to get easily readable, complete and useful reference for DRLVM
> Interface Reference and Java class library reference.
> In this connection, I've opened the following JIRAs including
> suggestions on improving Doxygen output. Would be great if you could
> find time to look through them and provide patches. The code
commenting
> BKMs [11] can be useful.
>
> [1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
>
> [2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
>
> [3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
> [4] http://issues.apache.org/jira/browse/HARMONY-3273
> Covers VM_GC interface and VM_Thread interface header files
>
> [5] http://issues.apache.org/jira/browse/HARMONY-3274
> Covers JNI and JVMTI interface header files
>
> [6] http://issues.apache.org/jira/browse/HARMONY-3275
> Covers Execution manager external interface headers
>
> [7] http://issues.apache.org/jira/browse/HARMONY-3277
> Covers Thread manager external interface headers
>
> [8] http://issues.apache.org/jira/browse/HARMONY-3278
> Covers Garbage collector and Execution engine external interface
> headers
>
> [9] http://issues.apache.org/jira/browse/HARMONY-3284
> Covers OS portability layer external interface
>
>
> Best regards,
> Sveta
>
> [10]
>
http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
> ml
> [11] http://wiki.apache.org/harmony/Code_Commenting
>
>
>
> -----Original Message-----
> From: Konovalova, Svetlana
> Sent: Wednesday, February 28, 2007 1:49 PM
> To: 'dev@harmony.apache.org'
> Subject: [drlvm]fix comments in vmcore external interface headers
> <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>
>
> >You can get involved in one of the following areas or open new JIRAs
> >with your own suggestions/fixes:
>
> Trying to improve scarce comments in VM Core external interface
headers,
> I've opened the following JIRAs with improvement suggestions:
>
> [1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
> [2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
> [3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
> Would be great if you could find time to look through the proposed
> changes and provide patches. :)
>
> Best regards,
> Sveta
> -----Original Message-----
> From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
> Sent: Tuesday, February 20, 2007 7:33 PM
> To: dev@harmony.apache.org
> Subject: [doxygen][doc] commenting bkms draft published on wiki
>
> Hi everyone,
> I have posted several tips/suggestions [1] about writing nice code
> comments in source header files for generating readable Doxygen
> reference materials [2]. These guidelines are to define some ground
> formatting and stylistic rules that would be good to follow when
adding
> comments to code.
> Your feedback is most welcome because together we can find the best
> solutions.
>
> The current reference documentation is often incomplete, out-of-date
> and/or not formatted correctly, which greatly decreases its
usefulness.
> Volunteers are very welcome to supply patches with more commented
code.
> The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
> so classlib input is also welcomed.
>
> You can get involved in one of the following areas or open new JIRAs
> with your own suggestions/fixes:
>
> [3] improving formatting of code comments so that Doxygen parses them
> correctly
> [4] enabling creation of structurally meaningful doc bundles and
adding
> intros (mainpage content) to each bundle
> [5] beautifying Doxygen output
> [6] monitoring quality and quantity of available Doxygen documentation
>
> Thanks,
> Nadya Morozova
>
> [1] http://wiki.apache.org/harmony/Code_Commenting
> [2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
> [3] https://issues.apache.org/jira/browse/HARMONY-2802
> [4] https://issues.apache.org/jira/browse/HARMONY-2814
> [5]
http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
>
> [6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
>
Re: [drlvm][doc] fix comments in vmcore external interface headers
Posted by Alexey Varlamov <al...@gmail.com>.
Sveta,
Have you seen HARMONY-3180 ([drlvm][doc] Improved portlib docs)?
It should address some of HARMONY-3284 items.
--
Alexey
2007/3/2, Konovalova, Svetlana <sv...@intel.com>:
> Dear all,
>
> Many source header files for generating readable Doxygen
> reference materials [10] lack ample and well-formatted comments. Our aim
> is to get easily readable, complete and useful reference for DRLVM
> Interface Reference and Java class library reference.
> In this connection, I've opened the following JIRAs including
> suggestions on improving Doxygen output. Would be great if you could
> find time to look through them and provide patches. The code commenting
> BKMs [11] can be useful.
>
> [1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
>
> [2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
>
> [3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
> [4] http://issues.apache.org/jira/browse/HARMONY-3273
> Covers VM_GC interface and VM_Thread interface header files
>
> [5] http://issues.apache.org/jira/browse/HARMONY-3274
> Covers JNI and JVMTI interface header files
>
> [6] http://issues.apache.org/jira/browse/HARMONY-3275
> Covers Execution manager external interface headers
>
> [7] http://issues.apache.org/jira/browse/HARMONY-3277
> Covers Thread manager external interface headers
>
> [8] http://issues.apache.org/jira/browse/HARMONY-3278
> Covers Garbage collector and Execution engine external interface
> headers
>
> [9] http://issues.apache.org/jira/browse/HARMONY-3284
> Covers OS portability layer external interface
>
>
> Best regards,
> Sveta
>
> [10]
> http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
> ml
> [11] http://wiki.apache.org/harmony/Code_Commenting
>
>
>
> -----Original Message-----
> From: Konovalova, Svetlana
> Sent: Wednesday, February 28, 2007 1:49 PM
> To: 'dev@harmony.apache.org'
> Subject: [drlvm]fix comments in vmcore external interface headers
> <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>
>
> >You can get involved in one of the following areas or open new JIRAs
> >with your own suggestions/fixes:
>
> Trying to improve scarce comments in VM Core external interface headers,
> I've opened the following JIRAs with improvement suggestions:
>
> [1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
> [2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
> [3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
> Would be great if you could find time to look through the proposed
> changes and provide patches. :)
>
> Best regards,
> Sveta
> -----Original Message-----
> From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
> Sent: Tuesday, February 20, 2007 7:33 PM
> To: dev@harmony.apache.org
> Subject: [doxygen][doc] commenting bkms draft published on wiki
>
> Hi everyone,
> I have posted several tips/suggestions [1] about writing nice code
> comments in source header files for generating readable Doxygen
> reference materials [2]. These guidelines are to define some ground
> formatting and stylistic rules that would be good to follow when adding
> comments to code.
> Your feedback is most welcome because together we can find the best
> solutions.
>
> The current reference documentation is often incomplete, out-of-date
> and/or not formatted correctly, which greatly decreases its usefulness.
> Volunteers are very welcome to supply patches with more commented code.
> The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
> so classlib input is also welcomed.
>
> You can get involved in one of the following areas or open new JIRAs
> with your own suggestions/fixes:
>
> [3] improving formatting of code comments so that Doxygen parses them
> correctly
> [4] enabling creation of structurally meaningful doc bundles and adding
> intros (mainpage content) to each bundle
> [5] beautifying Doxygen output
> [6] monitoring quality and quantity of available Doxygen documentation
>
> Thanks,
> Nadya Morozova
>
> [1] http://wiki.apache.org/harmony/Code_Commenting
> [2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
> [3] https://issues.apache.org/jira/browse/HARMONY-2802
> [4] https://issues.apache.org/jira/browse/HARMONY-2814
> [5] http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
>
> [6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
>
[drlvm][doc] new version of Doxygen docs published
Posted by "Morozova, Nadezhda" <na...@intel.com>.
Hi all,
I've deployed a fresher version of the Doxygen documentation generated
from DRLVM sources [1]. I've used the latest fixes from HARMONY-2814 and
further improved the infrastructure.
There are several open JIRAs with, but most commonly without, patches
that improve our documentation. I'll be looking at those and
regenerating docs as soon as some new comments get added. More patches
welcome ;)
I've also added simple instructions on generating Doxygen docs locally
[1], see Regenerating the Reference. You can now easily test the
comments you write.
[1] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
Cheers,
Nadya
>-----Original Message-----
>From: Konovalova, Svetlana [mailto:svetlana.konovalova@intel.com]
>Sent: Friday, March 02, 2007 3:10 PM
>To: dev@harmony.apache.org
>Subject: [drlvm][doc] fix comments in vmcore external interface headers
><was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>
>Dear all,
>
>Many source header files for generating readable Doxygen
>reference materials [10] lack ample and well-formatted comments. Our
aim
>is to get easily readable, complete and useful reference for DRLVM
>Interface Reference and Java class library reference.
>In this connection, I've opened the following JIRAs including
>suggestions on improving Doxygen output. Would be great if you could
>find time to look through them and provide patches. The code commenting
>BKMs [11] can be useful.
>
>[1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
>
>[2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
>
>[3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
>[4] http://issues.apache.org/jira/browse/HARMONY-3273
> Covers VM_GC interface and VM_Thread interface header files
>
>[5] http://issues.apache.org/jira/browse/HARMONY-3274
> Covers JNI and JVMTI interface header files
>
>[6] http://issues.apache.org/jira/browse/HARMONY-3275
> Covers Execution manager external interface headers
>
>[7] http://issues.apache.org/jira/browse/HARMONY-3277
> Covers Thread manager external interface headers
>
>[8] http://issues.apache.org/jira/browse/HARMONY-3278
> Covers Garbage collector and Execution engine external interface
>headers
>
>[9] http://issues.apache.org/jira/browse/HARMONY-3284
> Covers OS portability layer external interface
>
>
>Best regards,
>Sveta
>
>[10]
>http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.h
t
>ml
>[11] http://wiki.apache.org/harmony/Code_Commenting
>
>
>
>-----Original Message-----
>From: Konovalova, Svetlana
>Sent: Wednesday, February 28, 2007 1:49 PM
>To: 'dev@harmony.apache.org'
>Subject: [drlvm]fix comments in vmcore external interface headers
><was:RE: [doxygen][doc] commenting bkms draft published on wiki>
>
>
>>You can get involved in one of the following areas or open new JIRAs
>>with your own suggestions/fixes:
>
>Trying to improve scarce comments in VM Core external interface
headers,
>I've opened the following JIRAs with improvement suggestions:
>
>[1] http://issues.apache.org/jira/browse/HARMONY-3262
> Covers VM_Common interface header files
>[2] http://issues.apache.org/jira/browse/HARMONY-3263
> Covers VM_JIT and VM_EM interface header files
>[3] http://issues.apache.org/jira/browse/HARMONY-3264
> Covers VM_Interpreter interface header files
>
>Would be great if you could find time to look through the proposed
>changes and provide patches. :)
>
>Best regards,
>Sveta
>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Tuesday, February 20, 2007 7:33 PM
>To: dev@harmony.apache.org
>Subject: [doxygen][doc] commenting bkms draft published on wiki
>
>Hi everyone,
>I have posted several tips/suggestions [1] about writing nice code
>comments in source header files for generating readable Doxygen
>reference materials [2]. These guidelines are to define some ground
>formatting and stylistic rules that would be good to follow when adding
>comments to code.
>Your feedback is most welcome because together we can find the best
>solutions.
>
>The current reference documentation is often incomplete, out-of-date
>and/or not formatted correctly, which greatly decreases its usefulness.
>Volunteers are very welcome to supply patches with more commented code.
>The BKMs, samples and quoted bugs are mostly based on DRLVM materials,
>so classlib input is also welcomed.
>
>You can get involved in one of the following areas or open new JIRAs
>with your own suggestions/fixes:
>
>[3] improving formatting of code comments so that Doxygen parses them
>correctly
>[4] enabling creation of structurally meaningful doc bundles and adding
>intros (mainpage content) to each bundle
>[5] beautifying Doxygen output
>[6] monitoring quality and quantity of available Doxygen documentation
>
>Thanks,
>Nadya Morozova
>
>[1] http://wiki.apache.org/harmony/Code_Commenting
>[2] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
>[3] https://issues.apache.org/jira/browse/HARMONY-2802
>[4] https://issues.apache.org/jira/browse/HARMONY-2814
>[5]
http://wiki.apache.org/harmony/Doxygen_Docs_Look%26Feel_Improvements
>
>[6] http://wiki.apache.org/harmony/DRLVM_Documentation_Quality