harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Peter Novodvorsky" <peter.novodvor...@gmail.com>
Subject Re: [drlvm][doc] fix comments in vmcore external interface headers <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
Date Fri, 02 Mar 2007 12:33:23 GMT
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 <alexey.v.varlamov@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 <svetlana.konovalova@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
> >
>

Mime
View raw message