harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nathan Beyer" <ndbe...@apache.org>
Subject Re: [drlvm][doc] fix comments in vmcore external interface headers <was:RE: [doxygen][doc] commenting bkms draft published on wiki>
Date Sat, 03 Mar 2007 18:00:00 GMT
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 <peter.novodvorsky@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 <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