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:  Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Date: Wed, 29 Nov 2006 11:00:07 +0300
Message-ID: 
 <523F3D8D8C97554AA47E53DF1A05466A6D8EC9@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Thread-Index: AccTiVEQXNJdoawWQ7i4WYHJtdEMUgAAnjuA
From: "Morozova, Nadezhda" <nadezhda.morozova@intel.com>
To: <dev@harmony.apache.org>

>So, the answer is "No" because it is not committed. Thanks, I know the
>JIRA. Aren't we ready to commit these?
Well,
Largely, yes, though the config file does not allow for class hierarchy,
file lists and graphics. I hope Alexei can adjust the scripts to check
for the graphviz dot tool required for class diagrams.=20
Anyway, the scripts will be in the svn soon; I was also planning to
generate the whole bundle and deposit on my home - just as Paulex did
yesterday.=20

Cheers,=20
Nadya
=20
>-----Original Message-----
>From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>Sent: Wednesday, November 29, 2006 10:39 AM
>To: dev@harmony.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
>
>On the 0x22F day of Apache Harmony Nadezhda Morozova wrote:
>> >BTW, do we have vm.cfg committed as well as all other stuff
necessary
>> >to generate Doxygen docs?
>>
>> Yes, see JIRA 2024 and download the doc.scripts.zip bundle. It has
the
>> build file, the vm.cfg for Doxygen and the doc.properties to feed as
the
>> build targets.
>> Unload the files into the vm/doc/ directory and run ant. Should work.
>
>So, the answer is "No" because it is not committed. Thanks, I know the
>JIRA. Aren't we ready to commit these?
>
>> Cheers,
>> Nadya
>>
>>
>> >-----Original Message-----
>> >From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>> >Sent: Tuesday, November 28, 2006 2:20 PM
>> >To: dev@harmony.apache.org
>> >Subject: Re: [doc] What should be improved in DRLVM Doxygen
>> documentation?
>> >
>> >On the 0x22E day of Apache Harmony Nadezhda Morozova wrote:
>> >> Thanks for valuable feedback! We've got so many things to do.
>> >
>> >u r welcome :)
>> >
>> >> I've used the key JIRA for Doxygen docs that we have now:
>> >> http://issues.apache.org/jira/browse/HARMONY-2024 submitted by
Alexei
>> F.
>> >
>> >yes, I am looking in it too
>> >
>> >> There, we actually have two different doc sets:
>> >> Drlvm_intf_doc is for the whole bundle, and vm_doc.scripts.zip
>> enables
>> >> you to build component-wise documentation. Which one do we want?
>> >
>> >I prefer *full docs* for all source files so I could travel through
>> >the docs where I want. So, drlvm_intf_doc..
>> >
>> >> I've been thinking of how to best add Doxygen docs to the website,
>> >> suggest the following:
>> >>
>> >> standard/site/xdocs/subcomponents/classlib/doxygen/index.html -
for
>> >> classlib bundle(s).
>> >> standard/site/xdocs/subcomponents/drlvm/doxygen/index.html - for
>> drlvm
>> >> bundle(s).
>> >> standard/site/xdocs/stylesheets/* - for the config files and
scripts
>> to
>> >> build Doxygen documentation.
>> >> Any objections?
>> >
>> >Nadya, you have more expertise in this field :)
>> >
>> >BTW, do we have vm.cfg committed as well as all other stuff
necessary
>> >to generate Doxygen docs?
>> >
>> >> Cheers,
>> >> Nadya
>> >>
>> >>
>> >> >-----Original Message-----
>> >> >From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>> >> >Sent: Monday, November 27, 2006 1:04 PM
>> >> >To: dev@harmony.apache.org
>> >> >Subject: Re: [doc] What should be improved in DRLVM Doxygen
>> >> documentation?
>> >> >
>> >> >On the 0x22B day of Apache Harmony Alexei Fedotov wrote:
>> >> >> Ooops.... Sorry for incorrect word usage. I was intended to ask
>> who
>> >> >> will read Doxygen on our site and for which purpose. This would
>> help
>> >> >> us to understand what we should put there.
>> >> >
>> >> >From other projects I found Class hierarchy most useful in
Doxygen.
>> It
>> >> >is also useful for beginners to see the top-level structure of
the
>> >> >code in a comprehensive manner. See [1] as a live example of
on-site
>> >> >doxygen in an opensource project.
>> >> >
>> >> >I love to travel through the code in vim+ctags, but it is not the
>> best
>> >> >for all. So, I would vote for putting the Doxygen docs on the
site
>> as
>> >> >it should be useful. The sooner the better because it should help
>> >> >people express their opinions on _what should be improved_. Today
it
>> >> >is not easy to say $subj if you do not see the docs out there..
have
>> >> >to download 10MB, etc. etc.
>> >> >
>> >> >I should have said that long ago.. but.. too busy, sorry :(
>> >> >
>> >> >Today I downloaded th 10MB drlvm_intf_doc.zip and looking at it.
>> >> >Some comments:
>> >> >* header page is too brief
>> >> >* no class hierarchy & class inheritance sexy pictures
>> >> >* no source code browsing
>> >> >* per-file view wastes a lot of space
>> >> >
>> >> >Let's have the next step forward: put doxygen docs on the site!
And
>> >> >regenerate them regularly (=3Das snapshots appear, for
>> >> >example). How-to-improve opinions will come.
>> >> >
>> >> >[1]
>> http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
>> >> >
>> >> >> On 11/24/06, Alexei Fedotov <alexei.fedotov@gmail.com> wrote:
>> >> >> > All,
>> >> >> >
>> >> >> > Let me support Nadya's request. The first thing we need to do
is
>> to
>> >> >> > define what we are trying to achieve. Who is our target
>> auditory?
>> >> >> >
>> >> >> > 1. Egor said that he liked browsing object dependencies using
>> >> Doxygen.
>> >> >> > 2. Salikh said that he personally found browsing source files
>> much
>> >> more
>> >> >useful.
>> >> >> > 3. All my cases are about situations when one programmer used
>> >> >> > interfaces developed by another programmer.
>> >> >> >
>> >> >> > Could you please share your experience with wonderful
>> >> Doxygen/javadooc
>> >> >browsing?
>> >> >> >
>> >> >> >
>> >> >> > --
>> >> >> > Thank you,
>> >> >> > Alexei
>> >> >> >
>> >> >> > On 11/24/06, Morozova, Nadezhda <nadezhda.morozova@intel.com>
>> >> wrote:
>> >> >> > > Hi,
>> >> >> > >
>> >> >> > > I've tried out the scripts that build Doxygen docs for
DRLVM.
>> I
>> >> like
>> >> >the
>> >> >> > > resulting input immensely, though further improvements
might
>> be
>> >> >required
>> >> >> > > - will write specific suggestions later.
>> >> >> > >
>> >> >> > > At this point, my key question is the following: How do we
>> want
>> >> to
>> >> >> > > organize our docs? Possible solutions:
>> >> >> > > - harmony_intf_doc: classlib + drlvm docs, one huge bundle.
>> >> >> > >        Not sure it can work ok or be easy to maintain,
but...
>> >> >> > > - drlvm_intf_doc + classlib_intf_doc: two bundles;
>> >> >> > >        drlvm_intf was submitted by Alexei to the same JIRA
-
>> can
>> >> use
>> >> >as
>> >> >> > > a       starting point.
>> >> >> > > - separate bundles for each big component/module inside
>> >> >drlvm/classlib.
>> >> >> > >        This is how Alexei's scripts work now.
>> >> >> > >
>> >> >> > > To me, structuring into subdirs is fine. It helps browsing,
>> >> >localizing
>> >> >> > > specific files, works marvelously for the wiki metrics
>> pages...
>> >> >> > > BUT!
>> >> >> > > With subdirs, you never get a full list of
>> >> files/funcs/structs/etc
>> >> >for
>> >> >> > > the whole drlvm and if you search for a specific item,
you'll
>> >> have to
>> >> >go
>> >> >> > > from bundle to bundle.
>> >> >> > > This can be partially fixed by an opening page with links
to
>> >> specific
>> >> >> > > component bundles. However, indexing and search would still
be
>> >> >> > > component-wise only.
>> >> >> > >
>> >> >> > > There might be more arguments pro and contra. Everyone -
>> please
>> >> >express
>> >> >> > > your preference!
>> >> >> > >
>> >> >> > > PS: Alexei, thanks for a warm welcome, I'll work hard to
meet
>> >> your
>> >> >> > > expectations.
>> >> >> > >
>> >> >> > > Cheers,
>> >> >> > > Nadya
>> >> >> > >
>> >> >> > >
>> >> >> > > >-----Original Message-----
>> >> >> > > >From: Alexei Fedotov [mailto:alexei.fedotov@gmail.com]
>> >> >> > > >Sent: Friday, November 24, 2006 4:33 AM
>> >> >> > > >To: dev@harmony.apache.org
>> >> >> > > >Subject: Re: Re: [doc] What should be improved in DRLVM
>> Doxygen
>> >> >> > > >documentation?
>> >> >> > > >
>> >> >> > > >Nadya,
>> >> >> > > >
>> >> >> > > >My congratulations with your new role. Now I believe
nothing
>> >> will
>> >> >> > > >prevent Harmony web site and documentation from being the
>> best
>> >> and
>> >> >the
>> >> >> > > >coolest one. :-)
>> >> >> > > >
>> >> >> > > >I have prepared a documentation update according Andrey's
>> Wiki
>> >> page
>> >> >> > > >(with Egor's and Pavel's comments), see the last comment
to
>> >> >> > > >http://issues.apache.org/jira/browse/HARMONY-2024. The
>> >> documentation
>> >> >> > > >contains component bundles and inter-component interface
>> bundle.
>> >> If
>> >> >> > > >you find results useful, please don't hesitate to ask
>> questions
>> >> >about
>> >> >> > > >how it works.
>> >> >> > > >
>> >> >> > > >I also updated documentation metrics per bundle at the
Wiki
>> >> page:
>> >> >> > > >http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
>> >> >> > > >
>> >> >> > > >Many of .html files contain "The documentation for this
>> struct
>> >> was
>> >> >> > > >generated from the following file:" footer, so it
shouldn't
>> be a
>> >> >> > > >problem to understand which source file should be editied
to
>> >> improve
>> >> >> > > >the metrics.
>> >> >> > > >--
>> >> >> > > >Thank you,
>> >> >> > > >Alexei
>> >> >> > > >
>> >> >> > > >On 11/21/06, Morozova, Nadezhda
<nadezhda.morozova@intel.com>
>> >> wrote:
>> >> >> > > >>
>> >> >> > > >> >-----Original Message-----
>> >> >> > > >> >From: news [mailto:news@sea.gmane.org] On Behalf Of
Egor
>> >> Pasko
>> >> >> > > >> >Sent: Tuesday, November 21, 2006 7:42 AM
>> >> >> > > >> >To: dev@harmony.apache.org
>> >> >> > > >> >Subject: Re: [doc] What should be improved in DRLVM
>> Doxygen
>> >> >> > > >> documentation?
>> >> >> > > >> >
>> >> >> > > >> >On the 0x227 day of Apache Harmony Nadezhda Morozova
>> wrote:
>> >> >> > > >> >> That's a great start. Yes, if we have such a table as
>> the
>> >> front
>> >> >> > > page
>> >> >> > > >> for
>> >> >> > > >> >> Doxygen interfaces, it would be great. If you wish, I
>> can
>> >> >prepare
>> >> >> > > the
>> >> >> > > >> >> patch with the nice-looking version of it all.
>> >> >> > > >> >>
>> >> >> > > >> >> Questions:
>> >> >> > > >> >> - When building Doxygen, can we have a target for
inter-
>> >> >component
>> >> >> > > >> >> interfaces and for each component?
>> >> >> > > >> >> - if yes, should the files inside the include/
subfolder
>> be
>> >> >built
>> >> >> > > >> with
>> >> >> > > >> >> the component they belong to?
>> >> >> > > >> >> - For VM core and jit: any ideas on how to group
files
>> >> further?
>> >> >> > > The
>> >> >> > > >> >> current list of files belonging to vm core interfaces
is
>> >> *so*
>> >> >> > > long...
>> >> >> > > >> >> - Should we prepare docs for gcv4?
>> >> >> > > >> >
>> >> >> > > >> >IMO, the list of headers for Jitrino is too verbose.
For
>> >> >> > > >> >inter-component picture I suggest the following subset:
>> >> >> > > >> >vm/jitrino/src/dynopt/EdgeProfiler.h
>> >> >> > > >> >vm/jitrino/src/dynopt/StaticProfiler.h
>> >> >> > > >> >vm/jitrino/src/jet/jet.h
>> >> >> > > >> >vm/jitrino/src/main/Jitrino.h
>> >> >> > > >> >vm/jitrino/src/vm/drl/DrlEMInterface.h
>> >> >> > > >> >vm/jitrino/src/vm/drl/DrlVMInterface.h
>> >> >> > > >> >vm/jitrino/src/vm/EMInterface.h
>> >> >> > > >> >vm/jitrino/src/vm/VMInterface.h
>> >> >> > > >> >
>> >> >> > > >> >other headers are internal for Jitrino. So, the
suggestion
>> >> is: to
>> >> >> > > >> >document the mapping between *relevant* h-files and the
>> >> structure
>> >> >in
>> >> >> > > >> >the DevGuide
>> >> >> > > >> [Nadya]
>> >> >> > > >> I think we're mixing two different header groups. The
first
>> >> type
>> >> >is
>> >> >> > > >> *inter-component*, listed at the top of page on wiki.
The
>> >> devguide
>> >> >> > > shows
>> >> >> > > >> these interfaces in VM arch figure. As I understand,
these
>> are
>> >> the
>> >> >> > > >> interfaces that any jit must export:
>> >> >> > > >>
>> >> >> > > >>   Execution engine
>> >> >> > > >>   JIT_VM
>> >> >> > > >>      vm/include/internal_jit_intf.h
>> >> >> > > >>       vm/include/open/ee_em_intf.h
>> >> >> > > >> Not sure how these are related to files
>> >> >jitrino/src/vm/*Interface.h.
>> >> >> > > >>
>> >> >> > > >> The other group is *Interfaces inside the components*.
Here
>> I
>> >> >think
>> >> >> > > all
>> >> >> > > >> interfaces between internal parts of a component can go.
I
>> >> agree
>> >> >JIT
>> >> >> > > and
>> >> >> > > >> VM core seem to have too many headers, but they are all
in
>> the
>> >> dir
>> >> >> > > tree.
>> >> >> > > >> Don't you think we need to document them?
>> >> >> > > >>
>> >> >> > > >> My suggestion would be to add subgrouping for jit header
>> files
>> >> -
>> >> >and
>> >> >> > > >> possibly assign priorities to different groups. What do
you
>> >> say?
>> >> >> > > >>
>> >> >> > > >> >
>> >> >> > > >> >>
>> >> >> > > >> >> Thank you,
>> >> >> > > >> >> Nadya Morozova
>> >> >> > > >> >>
>> >> >> > > >> >>
>> >> >> > > >> >> >-----Original Message-----
>> >> >> > > >> >> >From: Andrey Yakushev
>> [mailto:andrey.yakushev@gmail.com]
>> >> >> > > >> >> >Sent: Monday, November 20, 2006 3:47 PM
>> >> >> > > >> >> >To: harmony-dev@incubator.apache.org
>> >> >> > > >> >> >Subject: Re: [doc] What should be improved in DRLVM
>> >> Doxygen
>> >> >> > > >> >> documentation?
>> >> >> > > >> >> >
>> >> >> > > >> >> >In order to understand the mapping between h-files
and
>> >> >structure
>> >> >> > > >> >> >described in the Developers guide I have tried to
>> prepare
>> >> some
>> >> >> > > >> initial
>> >> >> > > >> >> >classification. I put draft at
>> >> >> > > >> >>
>> >> >> > > >>
>> >> >> > >
>> >>
>>
>>http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifi
>> >> c
>> >> >> > > >> >> atio
>> >> >> > > >> >> >n.
>> >> >> > > >> >> >Probably such tables could be added to Doxygen doc;
of
>> >> course
>> >> >> > > after
>> >> >> > > >> >> >verification and rewriting it in more user friendly
>> >> manner.
>> >> >> > > >> >> >
>> >> >> > > >> >> >Is this helpful?
>> >> >> > > >> >> >
>> >> >> > > >> >> >Thanks,
>> >> >> > > >> >> >Andrey
>> >> >> > > >> >> >
>> >> >> > > >> >> >
>> >> >> > > >> >> >
>> >> >> > > >> >> >On 11/7/06, Mikhail Fursov <mike.fursov@gmail.com>
>> wrote:
>> >> >> > > >> >> >> On 07 Nov 2006 21:17:45 +0600, Egor Pasko
>> >> >> > > <egor.pasko@gmail.com>
>> >> >> > > >> >> wrote:
>> >> >> > > >> >> >>
>> >> >> > > >> >> >> > Do we feel that it is time to set
responsibilities
>> on
>> >> >> > > >> documenting
>> >> >> > > >> >> >> > vm/include/* ?
>> >> >> > > >> >> >>
>> >> >> > > >> >> >>
>> >> >> > > >> >> >> +1 To start working on intercomponent interfaces.
>> Going
>> >> to
>> >> >> > > commit
>> >> >> > > >> a
>> >> >> > > >> >> >couple
>> >> >> > > >> >> >> of EM interface files with documentation tomorrow.
I
>> do
>> >> not
>> >> >> > > >> believe
>> >> >> > > >> >> that
>> >> >> > > >> >> >> someday we will have all component's local code
>> >> documented
>> >> >(-1
>> >> >> > > to
>> >> >> > > >> >> make
>> >> >> > > >> >> >such
>> >> >> > > >> >> >> policy for patches), but intercomponent
documentation
>> is
>> >> >> > > something
>> >> >> > > >> we
>> >> >> > > >> >> >must
>> >> >> > > >> >> >> have (actually we must not only document but clean
>> the
>> >> code
>> >> >> > > too)
>> >> >> > > >> >> >>
>> >> >> > > >> >> >> --
>> >> >> > > >> >> >> Mikhail Fursov
>> >> >> > > >> >> >>
>> >> >> > > >> >> >>
>> >> >> > > >> >>
>> >> >> > > >> >
>> >> >> > > >> >--
>> >> >> > > >> >Egor Pasko
>> >> >> > > >>
>> >> >> > >
>> >> >> >
>> >> >>
>> >> >>
>> >> >> --
>> >> >> Thank you,
>> >> >> Alexei
>> >> >>
>> >> >
>> >> >--
>> >> >Egor Pasko
>> >>
>> >
>> >--
>> >Egor Pasko
>>
>
>--
>Egor Pasko