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: Mon, 27 Nov 2006 13:48:55 +0300
Message-ID: 
 <523F3D8D8C97554AA47E53DF1A05466A69AC7A@nnsmsx411.ccr.corp.intel.com>
Thread-Topic: Re: [doc] What should be improved in DRLVM Doxygen
 documentation?
Thread-Index: AccSC0j5DJAYaRZZQFCzORcL8uIDFgAA9tGw
From: "Morozova, Nadezhda" <nadezhda.morozova@intel.com>
To: <dev@harmony.apache.org>

Thanks for valuable feedback! We've got so many things to do.

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.
There, we actually have two different doc sets:=20
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?=20

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).=20
standard/site/xdocs/stylesheets/* - for the config files and scripts to
build Doxygen documentation.=20
Any objections?=20

Cheers,=20
Nadya
=20

>-----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